junis 0.3.9 → 0.3.11

package/dist/cli/index.js

@@ -165,6 +165,40 @@ function sleep(ms) {
 
 // src/relay/client.ts
 import WebSocket from "ws";
+
+// src/relay/upload.ts
+var LARGE_FILE_THRESHOLD = 5 * 1024 * 1024;
+async function uploadLargeFile(relay, base64Data, filename, contentType) {
+  const buffer = Buffer.from(base64Data, "base64");
+  const { put_url, access_url } = await relay.requestUploadUrl(
+    filename,
+    contentType,
+    buffer.length
+  );
+  const res = await fetch(put_url, {
+    method: "PUT",
+    headers: { "Content-Type": contentType },
+    body: buffer
+  });
+  if (!res.ok) {
+    throw new Error(`Upload failed: ${res.status} ${res.statusText}`);
+  }
+  return access_url;
+}
+function isLargeBase64(base64) {
+  return base64.length * 0.75 > LARGE_FILE_THRESHOLD;
+}
+function detectContentType(base64) {
+  const header = base64.slice(0, 16);
+  if (header.startsWith("/9j/")) return "image/jpeg";
+  if (header.startsWith("iVBOR")) return "image/png";
+  if (header.startsWith("R0lGO")) return "image/gif";
+  if (header.startsWith("UklGR")) return "image/webp";
+  if (header.startsWith("JVBER")) return "application/pdf";
+  return "application/octet-stream";
+}
+
+// src/relay/client.ts
 var JUNIS_WS = (() => {
   if (process.env.JUNIS_WS_URL) return process.env.JUNIS_WS_URL;
   const apiUrl = process.env.JUNIS_API_URL ?? "https://junis.ai";
@@ -186,6 +220,8 @@ var RelayClient = class {
   heartbeatTimer = null;
   destroyed = false;
   lastPongTime = 0;
+  // upload_url_response 대기용 pending 맵
+  pendingUploadRequests = /* @__PURE__ */ new Map();
   async connect() {
     if (this.destroyed) return;
     const url = `${JUNIS_WS}/ws/devices/${this.config.device_key}`;
@@ -209,9 +245,22 @@ var RelayClient = class {
           this.lastPongTime = Date.now();
           return;
         }
+        if (msg.type === "upload_url_response") {
+          const pending = this.pendingUploadRequests.get(msg.request_id);
+          if (pending) {
+            this.pendingUploadRequests.delete(msg.request_id);
+            if (msg.error) {
+              pending.reject(new Error(msg.error));
+            } else {
+              pending.resolve(msg);
+            }
+          }
+          return;
+        }
         if (msg.type === "mcp_request") {
           try {
-            const result = await this.onMCPRequest(msg.id, msg.payload);
+            let result = await this.onMCPRequest(msg.id, msg.payload);
+            result = await this.processLargeFiles(result);
             this.send({ type: "mcp_response", id: msg.id, payload: result });
           } catch (err) {
             this.send({
@@ -266,6 +315,76 @@ var RelayClient = class {
       this.ws.send(JSON.stringify(data));
     }
   }
+  /**
+   * 서버에 presigned PUT URL 요청.
+   * WebSocket으로 upload_url_request 전송 → upload_url_response 대기.
+   */
+  requestUploadUrl(filename, contentType, size) {
+    return new Promise((resolve, reject) => {
+      const requestId = crypto.randomUUID();
+      const timeout = setTimeout(() => {
+        this.pendingUploadRequests.delete(requestId);
+        reject(new Error("Upload URL request timeout (30s)"));
+      }, 3e4);
+      this.pendingUploadRequests.set(requestId, {
+        resolve: (data) => {
+          clearTimeout(timeout);
+          resolve(data);
+        },
+        reject: (err) => {
+          clearTimeout(timeout);
+          reject(err);
+        }
+      });
+      this.send({
+        type: "upload_url_request",
+        request_id: requestId,
+        filename,
+        content_type: contentType,
+        size
+      });
+    });
+  }
+  /**
+   * MCP 응답 내 대용량 base64 데이터를 감지하여 presigned URL 업로드 후 URL로 교체.
+   *
+   * 대상:
+   * 1. ImageContent: { type: "image", data: "<base64>", mimeType: "image/png" }
+   *    → { type: "text", text: "![uploaded](https://...access_url)" }
+   * 2. TextContent with large base64: { type: "text", text: "<huge base64>" }
+   *    → { type: "text", text: "https://...access_url" }
+   */
+  async processLargeFiles(result) {
+    if (!result || typeof result !== "object") return result;
+    const obj = result;
+    const inner = obj.result ?? obj;
+    const content = inner.content;
+    if (!Array.isArray(content)) return result;
+    for (let i = 0; i < content.length; i++) {
+      const item = content[i];
+      if (!item || typeof item !== "object") continue;
+      if (item.type === "image" && typeof item.data === "string" && isLargeBase64(item.data)) {
+        try {
+          const mimeType = item.mimeType || "image/png";
+          const ext = mimeType.split("/")[1] || "bin";
+          const url = await uploadLargeFile(this, item.data, `screenshot.${ext}`, mimeType);
+          content[i] = { type: "text", text: `![uploaded](${url})` };
+        } catch (err) {
+          console.error("Failed to upload large image:", err);
+        }
+      } else if (item.type === "text" && typeof item.text === "string" && isLargeBase64(item.text) && /^[A-Za-z0-9+/\n\r]+=*$/.test(item.text.trim())) {
+        try {
+          const contentType = detectContentType(item.text);
+          const ext = contentType.split("/")[1] || "bin";
+          const url = await uploadLargeFile(this, item.text, `file.${ext}`, contentType);
+          content[i] = { type: "text", text: url };
+        } catch (err) {
+          console.error("Failed to upload large text base64:", err);
+        }
+      }
+    }
+    return result;
+  }
   startHeartbeat() {
     this.heartbeatTimer = setInterval(() => {
       if (Date.now() - this.lastPongTime > 9e4) {
@@ -286,6 +405,10 @@ var RelayClient = class {
     this.destroyed = true;
     this.stopHeartbeat();
     this.ws?.close();
+    for (const [, pending] of this.pendingUploadRequests) {
+      pending.reject(new Error("Client destroyed"));
+    }
+    this.pendingUploadRequests.clear();
   }
 };
 
@@ -333,14 +456,17 @@ 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",
   kill_process: "confirm",
-  // 시스템 변경 — 기본 차단 (PDF 7.3절)
-  execute_command: "deny",
-  write_file: "deny"
+  // 시스템 변경 — 대화 기반 승인 (confirm)
+  execute_command: "confirm",
+  write_file: "confirm"
 };
 function checkPermission(toolName) {
   const level = toolPermissions[toolName];
@@ -364,19 +490,19 @@ 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:",
-        "- Safe, routine commands (ls, pwd, git status, echo): execute immediately without explanation.",
-        "- Destructive or irreversible commands (rm -rf, sudo, shutdown, mkfs): explain what will happen and get user confirmation first.",
+        "- Execute commands directly when the user requests them. Do not ask for confirmation \u2014 the user has already decided.",
         "- If a command fails, analyze the error and suggest an alternative. Do not retry the identical command more than twice.",
         "",
         "SAFETY:",
-        "- Commands run with the user's full permissions. Never execute commands that could damage the system, expose credentials, or modify security settings without explicit user request.",
-        "- Avoid piping untrusted input into shells. Use absolute paths when possible. Quote paths containing spaces."
+        "- Commands run with the user's full permissions. Use absolute paths when possible. Quote paths containing spaces."
       ].join("\n"),
       {
         command: z.string().describe("The shell command to execute. Use absolute paths when possible. Quote paths containing spaces."),
-        timeout_ms: z.number().optional().default(3e4).describe("Maximum execution time in milliseconds (default: 30000). Increase for long-running builds or downloads."),
+        timeout_ms: z.number().optional().default(12e4).describe("Maximum execution time in milliseconds (default: 120000). Increase for very long-running builds or downloads."),
         background: z.boolean().optional().default(false).describe("Run in background without waiting for completion. Use for servers or long-running processes.")
       },
       async ({ command, timeout_ms, background }) => {
@@ -863,11 +989,11 @@ var BrowserTools = class {
         headless: z2.boolean().optional().default(false).describe("Run without visible window (managed mode only). Use for background tasks."),
         cdpUrl: z2.string().optional().describe("Chrome DevTools Protocol URL for remote-cdp mode (e.g. http://localhost:9222)"),
         profile: z2.string().optional().describe("Browser profile name for persistent sessions \u2014 preserves cookies, logins, and history across restarts (managed mode only)"),
-        allowInternal: z2.boolean().optional().default(false).describe("Allow navigation to localhost and internal network URLs")
+        allowInternal: z2.boolean().optional().default(true).describe("Allow navigation to localhost and internal network URLs (default: true for local agent)")
       },
       ({ mode, headless, cdpUrl, profile, allowInternal }) => this.withLock(async () => {
         if (this.browser) {
-          return { content: [{ type: "text", text: "Browser is already running. Call browser_stop first." }] };
+          await this.cleanup();
         }
         if (mode === "remote-cdp") {
           if (!cdpUrl) throw new Error("cdpUrl is required for remote-cdp mode");
@@ -1404,7 +1530,11 @@ var DeviceTools = class {
         "Capture a photo from the device's camera and return it as base64 image data.",
         "",
         "Platform-specific: macOS (imagesnap), Windows (ffmpeg/dshow), Linux (fswebcam).",
-        "Requires a connected camera with OS permissions granted. If output_path is provided, the file is also saved to disk."
+        "If output_path is provided, the file is also saved to disk.",
+        "",
+        "PERMISSIONS (macOS): Camera permission is needed. If it fails, macOS may show a native Allow/Deny dialog \u2014 ask the user to click Allow.",
+        "If still denied, use execute_command to open Camera settings:",
+        "  open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Camera'"
       ].join("\n"),
       {
         output_path: z4.string().optional().describe("File path to save the captured photo. If omitted, returns image data only (temp file auto-cleaned).")
@@ -1422,11 +1552,10 @@ var DeviceTools = class {
           await execAsync3(cmd);
         } catch (err) {
           const e = err;
+          const hint = p === "mac" ? "\n\n\u{1F527} FIX: Camera permission may be needed. Try:\n1. Retry \u2014 macOS may show a native Allow/Deny dialog.\n2. If denied, run via execute_command:  open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Camera'\nAsk the user to toggle ON for 'imagesnap' (or their terminal app), then retry." : "";
           return {
-            content: [{ type: "text", text: `\u274C Camera not found or inaccessible.
-Cause: ${e.message}
-
-Please check if a camera is connected.` }],
+            content: [{ type: "text", text: `\u274C Camera capture failed.
+Cause: ${e.message}${hint}` }],
             isError: true
           };
         }
@@ -1502,7 +1631,11 @@ Please check if a camera is connected.` }],
         "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"),
@@ -1592,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...");
@@ -1603,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);
@@ -1625,6 +1777,17 @@ var APP_BLACKLIST = /* @__PURE__ */ new Set([
 ]);
 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."
+].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"]);
@@ -1632,11 +1795,13 @@ async function peekaboo(args) {
     return JSON.parse(stdout);
   } 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}`);
   }
 }
 function checkBlacklist(app) {
@@ -1651,10 +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: 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.",
         "",
-        "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.")
@@ -1688,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"),
       {
@@ -1714,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"),
@@ -1738,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"),
       {
@@ -1761,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"),
       {
@@ -1798,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}`);
         }
       }
     );
@@ -1812,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.")
@@ -1836,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}`);
         }
       }
     );
@@ -1852,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"),
       {
@@ -1889,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"),
       {
@@ -1907,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,14 +42,17 @@ 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",
   kill_process: "confirm",
-  // 시스템 변경 — 기본 차단 (PDF 7.3절)
-  execute_command: "deny",
-  write_file: "deny"
+  // 시스템 변경 — 대화 기반 승인 (confirm)
+  execute_command: "confirm",
+  write_file: "confirm"
 };
 function checkPermission(toolName) {
   const level = toolPermissions[toolName];
@@ -73,19 +76,19 @@ 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:",
-        "- Safe, routine commands (ls, pwd, git status, echo): execute immediately without explanation.",
-        "- Destructive or irreversible commands (rm -rf, sudo, shutdown, mkfs): explain what will happen and get user confirmation first.",
+        "- Execute commands directly when the user requests them. Do not ask for confirmation \u2014 the user has already decided.",
         "- If a command fails, analyze the error and suggest an alternative. Do not retry the identical command more than twice.",
         "",
         "SAFETY:",
-        "- Commands run with the user's full permissions. Never execute commands that could damage the system, expose credentials, or modify security settings without explicit user request.",
-        "- Avoid piping untrusted input into shells. Use absolute paths when possible. Quote paths containing spaces."
+        "- Commands run with the user's full permissions. Use absolute paths when possible. Quote paths containing spaces."
       ].join("\n"),
       {
         command: z.string().describe("The shell command to execute. Use absolute paths when possible. Quote paths containing spaces."),
-        timeout_ms: z.number().optional().default(3e4).describe("Maximum execution time in milliseconds (default: 30000). Increase for long-running builds or downloads."),
+        timeout_ms: z.number().optional().default(12e4).describe("Maximum execution time in milliseconds (default: 120000). Increase for very long-running builds or downloads."),
         background: z.boolean().optional().default(false).describe("Run in background without waiting for completion. Use for servers or long-running processes.")
       },
       async ({ command, timeout_ms, background }) => {
@@ -572,11 +575,11 @@ var BrowserTools = class {
         headless: z2.boolean().optional().default(false).describe("Run without visible window (managed mode only). Use for background tasks."),
         cdpUrl: z2.string().optional().describe("Chrome DevTools Protocol URL for remote-cdp mode (e.g. http://localhost:9222)"),
         profile: z2.string().optional().describe("Browser profile name for persistent sessions \u2014 preserves cookies, logins, and history across restarts (managed mode only)"),
-        allowInternal: z2.boolean().optional().default(false).describe("Allow navigation to localhost and internal network URLs")
+        allowInternal: z2.boolean().optional().default(true).describe("Allow navigation to localhost and internal network URLs (default: true for local agent)")
       },
       ({ mode, headless, cdpUrl, profile, allowInternal }) => this.withLock(async () => {
         if (this.browser) {
-          return { content: [{ type: "text", text: "Browser is already running. Call browser_stop first." }] };
+          await this.cleanup();
         }
         if (mode === "remote-cdp") {
           if (!cdpUrl) throw new Error("cdpUrl is required for remote-cdp mode");
@@ -1113,7 +1116,11 @@ var DeviceTools = class {
         "Capture a photo from the device's camera and return it as base64 image data.",
         "",
         "Platform-specific: macOS (imagesnap), Windows (ffmpeg/dshow), Linux (fswebcam).",
-        "Requires a connected camera with OS permissions granted. If output_path is provided, the file is also saved to disk."
+        "If output_path is provided, the file is also saved to disk.",
+        "",
+        "PERMISSIONS (macOS): Camera permission is needed. If it fails, macOS may show a native Allow/Deny dialog \u2014 ask the user to click Allow.",
+        "If still denied, use execute_command to open Camera settings:",
+        "  open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Camera'"
       ].join("\n"),
       {
         output_path: z4.string().optional().describe("File path to save the captured photo. If omitted, returns image data only (temp file auto-cleaned).")
@@ -1131,11 +1138,10 @@ var DeviceTools = class {
           await execAsync3(cmd);
         } catch (err) {
           const e = err;
+          const hint = p === "mac" ? "\n\n\u{1F527} FIX: Camera permission may be needed. Try:\n1. Retry \u2014 macOS may show a native Allow/Deny dialog.\n2. If denied, run via execute_command:  open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Camera'\nAsk the user to toggle ON for 'imagesnap' (or their terminal app), then retry." : "";
           return {
-            content: [{ type: "text", text: `\u274C Camera not found or inaccessible.
-Cause: ${e.message}
-
-Please check if a camera is connected.` }],
+            content: [{ type: "text", text: `\u274C Camera capture failed.
+Cause: ${e.message}${hint}` }],
             isError: true
           };
         }
@@ -1211,7 +1217,11 @@ Please check if a camera is connected.` }],
         "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"),
@@ -1301,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...");
@@ -1312,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);
@@ -1334,6 +1363,17 @@ var APP_BLACKLIST = /* @__PURE__ */ new Set([
 ]);
 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."
+].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"]);
@@ -1341,11 +1381,13 @@ async function peekaboo(args) {
     return JSON.parse(stdout);
   } 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}`);
   }
 }
 function checkBlacklist(app) {
@@ -1360,10 +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.",
         "",
-        "SAFETY: Terminal, iTerm, and Finder are blocked. Two consecutive failures trigger an automatic safety stop."
+        "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.",
+        "",
+        "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.")
@@ -1397,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"),
       {
@@ -1423,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"),
@@ -1447,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"),
       {
@@ -1470,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"),
       {
@@ -1507,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}`);
         }
       }
     );
@@ -1521,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.")
@@ -1545,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}`);
         }
       }
     );
@@ -1561,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"),
       {
@@ -1598,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"),
       {
@@ -1616,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,14 +43,17 @@ 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",
   kill_process: "confirm",
-  // 시스템 변경 — 기본 차단 (PDF 7.3절)
-  execute_command: "deny",
-  write_file: "deny"
+  // 시스템 변경 — 대화 기반 승인 (confirm)
+  execute_command: "confirm",
+  write_file: "confirm"
 };
 function checkPermission(toolName) {
   const level = toolPermissions[toolName];
@@ -74,19 +77,19 @@ 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:",
-        "- Safe, routine commands (ls, pwd, git status, echo): execute immediately without explanation.",
-        "- Destructive or irreversible commands (rm -rf, sudo, shutdown, mkfs): explain what will happen and get user confirmation first.",
+        "- Execute commands directly when the user requests them. Do not ask for confirmation \u2014 the user has already decided.",
         "- If a command fails, analyze the error and suggest an alternative. Do not retry the identical command more than twice.",
         "",
         "SAFETY:",
-        "- Commands run with the user's full permissions. Never execute commands that could damage the system, expose credentials, or modify security settings without explicit user request.",
-        "- Avoid piping untrusted input into shells. Use absolute paths when possible. Quote paths containing spaces."
+        "- Commands run with the user's full permissions. Use absolute paths when possible. Quote paths containing spaces."
       ].join("\n"),
       {
         command: z.string().describe("The shell command to execute. Use absolute paths when possible. Quote paths containing spaces."),
-        timeout_ms: z.number().optional().default(3e4).describe("Maximum execution time in milliseconds (default: 30000). Increase for long-running builds or downloads."),
+        timeout_ms: z.number().optional().default(12e4).describe("Maximum execution time in milliseconds (default: 120000). Increase for very long-running builds or downloads."),
         background: z.boolean().optional().default(false).describe("Run in background without waiting for completion. Use for servers or long-running processes.")
       },
       async ({ command, timeout_ms, background }) => {
@@ -573,11 +576,11 @@ var BrowserTools = class {
         headless: z2.boolean().optional().default(false).describe("Run without visible window (managed mode only). Use for background tasks."),
         cdpUrl: z2.string().optional().describe("Chrome DevTools Protocol URL for remote-cdp mode (e.g. http://localhost:9222)"),
         profile: z2.string().optional().describe("Browser profile name for persistent sessions \u2014 preserves cookies, logins, and history across restarts (managed mode only)"),
-        allowInternal: z2.boolean().optional().default(false).describe("Allow navigation to localhost and internal network URLs")
+        allowInternal: z2.boolean().optional().default(true).describe("Allow navigation to localhost and internal network URLs (default: true for local agent)")
       },
       ({ mode, headless, cdpUrl, profile, allowInternal }) => this.withLock(async () => {
         if (this.browser) {
-          return { content: [{ type: "text", text: "Browser is already running. Call browser_stop first." }] };
+          await this.cleanup();
         }
         if (mode === "remote-cdp") {
           if (!cdpUrl) throw new Error("cdpUrl is required for remote-cdp mode");
@@ -1114,7 +1117,11 @@ var DeviceTools = class {
         "Capture a photo from the device's camera and return it as base64 image data.",
         "",
         "Platform-specific: macOS (imagesnap), Windows (ffmpeg/dshow), Linux (fswebcam).",
-        "Requires a connected camera with OS permissions granted. If output_path is provided, the file is also saved to disk."
+        "If output_path is provided, the file is also saved to disk.",
+        "",
+        "PERMISSIONS (macOS): Camera permission is needed. If it fails, macOS may show a native Allow/Deny dialog \u2014 ask the user to click Allow.",
+        "If still denied, use execute_command to open Camera settings:",
+        "  open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Camera'"
       ].join("\n"),
       {
         output_path: z4.string().optional().describe("File path to save the captured photo. If omitted, returns image data only (temp file auto-cleaned).")
@@ -1132,11 +1139,10 @@ var DeviceTools = class {
           await execAsync3(cmd);
         } catch (err) {
           const e = err;
+          const hint = p === "mac" ? "\n\n\u{1F527} FIX: Camera permission may be needed. Try:\n1. Retry \u2014 macOS may show a native Allow/Deny dialog.\n2. If denied, run via execute_command:  open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Camera'\nAsk the user to toggle ON for 'imagesnap' (or their terminal app), then retry." : "";
           return {
-            content: [{ type: "text", text: `\u274C Camera not found or inaccessible.
-Cause: ${e.message}
-
-Please check if a camera is connected.` }],
+            content: [{ type: "text", text: `\u274C Camera capture failed.
+Cause: ${e.message}${hint}` }],
             isError: true
           };
         }
@@ -1212,7 +1218,11 @@ Please check if a camera is connected.` }],
         "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.9",
+  "version": "0.3.11",
   "description": "One-line device control for AI agents",
   "type": "module",
   "bin": {