junis 0.3.10 → 0.3.11

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: opening System Preferences URLs for permissions (e.g. 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,11 @@ 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. 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."
       ].join("\n"),
       {
         action: z4.enum(["start", "stop"]).describe("'start': begin recording, 'stop': end recording and save the file"),
@@ -1716,10 +1725,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 +1754,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);
@@ -1756,6 +1784,10 @@ var PERM_FIX_HINT = [
   "3. Accessibility:  open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility'",
   "Toggle ON for 'peekaboo' in the opened panel, then retry."
 ].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 +1795,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,17 +1816,24 @@ 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): use desktop_screenshot + coordinate-based desktop_click instead.",
+        "- 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.",
         "",
-        "PERMISSIONS: Desktop tools require macOS Accessibility + Screen Recording permissions for 'peekaboo'.",
-        "If a tool fails with permission error, use execute_command to:",
-        "  1. peekaboo permissions --json-output  (check which are missing)",
+        "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'",
-        "Ask the user to toggle ON for 'peekaboo', then retry.",
+        "Toggle ON for 'peekaboo', then retry.",
         "",
-        "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.")
@@ -1829,6 +1867,8 @@ var DesktopTools = class {
         "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.",
         "",
+        "PERMISSIONS: Requires macOS Accessibility permission for 'peekaboo'.",
+        "",
         "SAFETY: Terminal, iTerm, and Finder are blocked. Two consecutive failures trigger automatic safety stop."
       ].join("\n"),
       {
@@ -1855,6 +1895,9 @@ var DesktopTools = class {
         "Type text into the currently focused UI element on macOS. The text is sent as keyboard input character-by-character.",
         "",
         "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.",
+        "",
+        "PERMISSIONS: Requires macOS Accessibility permission for 'peekaboo'.",
         "",
         "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
@@ -1879,6 +1922,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'.",
+        "",
         "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
@@ -1902,6 +1947,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'.",
+        "",
         "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
@@ -1939,11 +1986,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 +2002,9 @@ 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 macOS Accessibility permission for 'peekaboo'."
       ].join("\n"),
       {
         app: z5.string().optional().describe("Filter by app name. Omit to query the frontmost app.")
@@ -1977,11 +2028,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}`);
         }
       }
     );
@@ -1993,6 +2046,8 @@ var DesktopTools = class {
         "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'.",
+        "",
         "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
@@ -2030,6 +2085,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'.",
+        "",
         "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
@@ -2048,14 +2105,82 @@ 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. Use this for Korean, Japanese, Chinese, emoji, or any non-ASCII text.",
+        "",
+        "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.",
+        "",
+        "PERMISSIONS: Requires macOS Accessibility permission for 'peekaboo'.",
+        "",
+        "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)"),
+        app: z5.string().optional().describe("App name to focus before pasting")
+      },
+      async ({ text, app }) => {
+        checkBlacklist(app);
+        const args = ["type", "--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.",
+        "",
+        "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.",
+        "",
+        "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);
+        await execa("open", ["-a", app]);
+        await new Promise((r) => setTimeout(r, 1500));
+        return {
+          content: [{ type: "text", text: `Launched ${app}` }]
+        };
+      }
+    );
+    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.",
+        "",
+        "Examples: 'https://google.com', 'file:///path/to/file.html', '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')")
+      },
+      async ({ url, app }) => {
+        const args = app ? ["-a", app, url] : [url];
+        await execa("open", args);
+        return {
+          content: [{ type: "text", text: `Opened: ${url}` }]
+        };
+      }
+    );
   }
 };
 

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: opening System Preferences URLs for permissions (e.g. 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,11 @@ 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. 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."
       ].join("\n"),
       {
         action: z4.enum(["start", "stop"]).describe("'start': begin recording, 'stop': end recording and save the file"),
@@ -1302,10 +1311,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 +1340,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);
@@ -1342,6 +1370,10 @@ var PERM_FIX_HINT = [
   "3. Accessibility:  open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility'",
   "Toggle ON for 'peekaboo' in the opened panel, then retry."
 ].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 +1381,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,17 +1402,24 @@ 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): use desktop_screenshot + coordinate-based desktop_click instead.",
+        "- 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.",
         "",
-        "PERMISSIONS: Desktop tools require macOS Accessibility + Screen Recording permissions for 'peekaboo'.",
-        "If a tool fails with permission error, use execute_command to:",
-        "  1. peekaboo permissions --json-output  (check which are missing)",
+        "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'",
-        "Ask the user to toggle ON for 'peekaboo', then retry.",
+        "Toggle ON for 'peekaboo', then retry.",
         "",
-        "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.")
@@ -1415,6 +1453,8 @@ var DesktopTools = class {
         "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.",
         "",
+        "PERMISSIONS: Requires macOS Accessibility permission for 'peekaboo'.",
+        "",
         "SAFETY: Terminal, iTerm, and Finder are blocked. Two consecutive failures trigger automatic safety stop."
       ].join("\n"),
       {
@@ -1441,6 +1481,9 @@ var DesktopTools = class {
         "Type text into the currently focused UI element on macOS. The text is sent as keyboard input character-by-character.",
         "",
         "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.",
+        "",
+        "PERMISSIONS: Requires macOS Accessibility permission for 'peekaboo'.",
         "",
         "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
@@ -1465,6 +1508,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'.",
+        "",
         "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
@@ -1488,6 +1533,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'.",
+        "",
         "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
@@ -1525,11 +1572,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 +1588,9 @@ 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 macOS Accessibility permission for 'peekaboo'."
       ].join("\n"),
       {
         app: z5.string().optional().describe("Filter by app name. Omit to query the frontmost app.")
@@ -1563,11 +1614,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}`);
         }
       }
     );
@@ -1579,6 +1632,8 @@ var DesktopTools = class {
         "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'.",
+        "",
         "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
@@ -1616,6 +1671,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'.",
+        "",
         "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
@@ -1634,14 +1691,82 @@ 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. Use this for Korean, Japanese, Chinese, emoji, or any non-ASCII text.",
+        "",
+        "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.",
+        "",
+        "PERMISSIONS: Requires macOS Accessibility permission for 'peekaboo'.",
+        "",
+        "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)"),
+        app: z5.string().optional().describe("App name to focus before pasting")
+      },
+      async ({ text, app }) => {
+        checkBlacklist(app);
+        const args = ["type", "--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.",
+        "",
+        "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.",
+        "",
+        "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);
+        await execa("open", ["-a", app]);
+        await new Promise((r) => setTimeout(r, 1500));
+        return {
+          content: [{ type: "text", text: `Launched ${app}` }]
+        };
+      }
+    );
+    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.",
+        "",
+        "Examples: 'https://google.com', 'file:///path/to/file.html', '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')")
+      },
+      async ({ url, app }) => {
+        const args = app ? ["-a", app, url] : [url];
+        await execa("open", args);
+        return {
+          content: [{ type: "text", text: `Opened: ${url}` }]
+        };
+      }
+    );
   }
 };
 

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: opening System Preferences URLs for permissions (e.g. 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,11 @@ 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. 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."
       ].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.11",
   "description": "One-line device control for AI agents",
   "type": "module",
   "bin": {