junis 0.3.8 → 0.3.10

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();
   }
 };
 
@@ -338,9 +461,9 @@ var toolPermissions = {
   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];
@@ -366,17 +489,15 @@ var FilesystemTools = class {
         "- For reading files prefer read_file, for editing prefer edit_block, for searching prefer search_code.",
         "",
         "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 +984,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 +1525,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 +1547,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
           };
         }
@@ -1625,6 +1749,13 @@ 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");
 async function peekaboo(args) {
   try {
     const { stdout } = await execa("peekaboo", [...args, "--json-output"]);
@@ -1632,11 +1763,14 @@ 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 : "";
     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: ${err.message}${hint}`);
     }
-    throw err;
+    throw new Error(`${err.message}${hint}`);
   }
 }
 function checkBlacklist(app) {
@@ -1654,6 +1788,13 @@ var DesktopTools = class {
         "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).",
         "",
+        "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)",
+        "  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.",
+        "",
         "SAFETY: Terminal, iTerm, and Finder are blocked. Two consecutive failures trigger an automatic safety stop."
       ].join("\n"),
       {

package/dist/server/mcp.js

@@ -47,9 +47,9 @@ var toolPermissions = {
   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];
@@ -75,17 +75,15 @@ var FilesystemTools = class {
         "- For reading files prefer read_file, for editing prefer edit_block, for searching prefer search_code.",
         "",
         "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 +570,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 +1111,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 +1133,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
           };
         }
@@ -1334,6 +1335,13 @@ 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");
 async function peekaboo(args) {
   try {
     const { stdout } = await execa("peekaboo", [...args, "--json-output"]);
@@ -1341,11 +1349,14 @@ 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 : "";
     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: ${err.message}${hint}`);
     }
-    throw err;
+    throw new Error(`${err.message}${hint}`);
   }
 }
 function checkBlacklist(app) {
@@ -1363,6 +1374,13 @@ var DesktopTools = class {
         "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).",
         "",
+        "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)",
+        "  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.",
+        "",
         "SAFETY: Terminal, iTerm, and Finder are blocked. Two consecutive failures trigger an automatic safety stop."
       ].join("\n"),
       {

package/dist/server/stdio.js

@@ -48,9 +48,9 @@ var toolPermissions = {
   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];
@@ -76,17 +76,15 @@ var FilesystemTools = class {
         "- For reading files prefer read_file, for editing prefer edit_block, for searching prefer search_code.",
         "",
         "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 +571,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 +1112,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 +1134,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
           };
         }

package/package.json

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