junis 0.3.7 → 0.3.8

package/dist/cli/index.js

@@ -1626,7 +1626,6 @@ var APP_BLACKLIST = /* @__PURE__ */ new Set([
 var consecutiveFailures = 0;
 var MAX_CONSECUTIVE_FAILURES = 2;
 async function peekaboo(args) {
-  consecutiveFailures = 0;
   try {
     const { stdout } = await execa("peekaboo", [...args, "--json-output"]);
     consecutiveFailures = 0;
@@ -1650,10 +1649,10 @@ var DesktopTools = class {
     server.tool(
       "desktop_see",
       [
-        "Capture the macOS Accessibility Tree snapshot for a running application. Returns structured element list with IDs, roles, labels, and positions.",
+        "Capture the macOS Accessibility Tree snapshot for a running application. Returns a structured element list with IDs, roles, labels, and positions.",
         "",
-        "WORKFLOW: Call desktop_see \u2192 find target element \u2192 use its ID in desktop_click or desktop_type.",
-        "Pass the returned snapshotId to subsequent calls for 240x speed improvement (cached lookup vs. full re-scan).",
+        "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).",
         "",
         "SAFETY: Terminal, iTerm, and Finder are blocked. Two consecutive failures trigger an automatic safety stop."
       ].join("\n"),
@@ -1686,15 +1685,15 @@ var DesktopTools = class {
       [
         "Click a macOS UI element by its accessibility label, ID, or x,y coordinates.",
         "",
-        "The 'on' parameter accepts: element label text (e.g. 'Save'), accessibility ID from desktop_see, or coordinates as 'x,y' string.",
-        "For faster interaction, pass the snapshotId from a recent desktop_see call.",
+        "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.",
         "",
         "SAFETY: Terminal, iTerm, and Finder are blocked. Two consecutive failures trigger automatic safety stop."
       ].join("\n"),
       {
         on: z5.string().describe("Element label, accessibility ID, or 'x,y' coordinates to click"),
         app: z5.string().optional().describe("App name to target (e.g. 'Safari')"),
-        snapshot: z5.string().optional().describe("snapshotId from desktop_see for cached interaction (240x faster)"),
+        snapshot: z5.string().optional().describe("snapshotId from a previous accessibility tree capture for cached interaction (240x faster)"),
         doubleClick: z5.boolean().optional().default(false).describe("Double-click instead of single click")
       },
       async ({ on, app, snapshot, doubleClick }) => {
@@ -1714,7 +1713,9 @@ var DesktopTools = class {
       [
         "Type text into the currently focused UI element on macOS. The text is sent as keyboard input character-by-character.",
         "",
-        "SAFETY: Terminal, iTerm, and Finder are blocked. Use desktop_see first to verify the correct element is focused."
+        "IMPORTANT: Always capture the accessibility tree first to verify the correct element is focused before typing.",
+        "",
+        "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
         text: z5.string().describe("Text to type into the focused element"),
@@ -1755,11 +1756,17 @@ var DesktopTools = class {
     );
     server.tool(
       "desktop_scroll",
-      "Scroll within a macOS application or specific UI element. Use 'ticks' to control scroll distance (default: 3). Can target a specific element by label or ID with the 'on' parameter.",
+      [
+        "Scroll within a macOS application or specific UI element.",
+        "",
+        "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.",
+        "",
+        "SAFETY: Terminal, iTerm, and Finder are blocked."
+      ].join("\n"),
       {
         direction: z5.enum(["up", "down", "left", "right"]).describe("Scroll direction"),
         ticks: z5.number().optional().default(3).describe("Number of scroll ticks (default: 3). Higher = more scrolling."),
-        on: z5.string().optional().describe("Element label or ID to scroll within (from desktop_see). Omit to scroll the active area."),
+        on: z5.string().optional().describe("Element label or ID to scroll within (from a previous accessibility tree capture). Omit to scroll the active area."),
         app: z5.string().optional().describe("App name to target")
       },
       async ({ direction, ticks, on, app }) => {
@@ -1775,23 +1782,38 @@ var DesktopTools = class {
     );
     server.tool(
       "desktop_list_apps",
-      "List all currently running applications on macOS. Returns app names that can be used as the 'app' parameter in other desktop tools (desktop_see, desktop_click, desktop_type, etc.).",
+      [
+        "List all currently running applications on macOS. Returns app names usable as the 'app' parameter in all other desktop tools.",
+        "",
+        "WORKFLOW: This is typically the first step \u2014 identify which apps are running before interacting with their UI.",
+        "The returned names are exact strings to pass as 'app' (e.g. 'Safari', 'Google Chrome', 'Notes')."
+      ].join("\n"),
       {},
       async () => {
         try {
           const { stdout } = await execa("peekaboo", ["list", "apps", "--json"]);
+          consecutiveFailures = 0;
           return {
             content: [{ type: "text", text: stdout }]
           };
         } catch (err) {
           consecutiveFailures++;
+          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 err;
         }
       }
     );
     server.tool(
       "desktop_list_windows",
-      "List all open windows on macOS, optionally filtered by app name. If no app is specified, lists windows for the frontmost application. Useful for identifying which windows are available for automation.",
+      [
+        "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."
+      ].join("\n"),
       {
         app: z5.string().optional().describe("Filter by app name. Omit to query the frontmost app.")
       },
@@ -1808,11 +1830,16 @@ var DesktopTools = class {
           }
           const args = ["list", "windows", "--app", targetApp, "--json"];
           const { stdout } = await execa("peekaboo", args);
+          consecutiveFailures = 0;
           return {
             content: [{ type: "text", text: stdout }]
           };
         } catch (err) {
           consecutiveFailures++;
+          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 err;
         }
       }
@@ -1820,10 +1847,12 @@ var DesktopTools = class {
     server.tool(
       "desktop_screenshot",
       [
-        "Take a high-quality macOS screenshot using Peekaboo (Retina display support). Returns base64 image data.",
+        "Take a high-quality macOS screenshot (Retina display support). Returns base64 image data.",
         "",
         "MODES: 'screen' captures the full display, 'window' captures a specific app window.",
-        "Prefer desktop_see (Accessibility Tree) for understanding UI structure \u2014 use screenshot only when visual appearance matters (layouts, images, colors)."
+        "TIP: Prefer the accessibility tree for understanding UI structure \u2014 use screenshots only when visual appearance matters (layouts, images, colors).",
+        "",
+        "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
         app: z5.string().optional().describe("Capture a specific app's window (by name)"),
@@ -1855,10 +1884,12 @@ var DesktopTools = class {
     server.tool(
       "desktop_menu",
       [
-        "Click a menu bar item in a macOS application. Navigate nested menus by adding path segments.",
+        "Click a menu bar item in a macOS application. Navigate nested menus by providing path segments.",
         "",
         "Examples: ['File', 'New Tab'], ['Edit', 'Find', 'Find...'], ['View', 'Enter Full Screen'].",
-        "The target app must be running and accessible."
+        "Omit the 'app' parameter to target the frontmost app. The target app must be running.",
+        "",
+        "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
         path: z5.array(z5.string()).describe("Menu path as array (e.g. ['File', 'Save'], ['Edit', 'Find', 'Find...'])"),
@@ -1870,11 +1901,16 @@ var DesktopTools = class {
         if (app) args.push("--app", app);
         try {
           const { stdout } = await execa("peekaboo", args);
+          consecutiveFailures = 0;
           return {
             content: [{ type: "text", text: stdout || "Menu click executed" }]
           };
         } catch (err) {
           consecutiveFailures++;
+          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 err;
         }
       }
@@ -2613,6 +2649,8 @@ program.command("start", { isDefault: true }).description("Start Junis agent con
         console.log("");
       }
     } else {
+      const oldDeviceKey = config2.device_key;
+      const oldToken = config2.token;
       const checked = await checkEnsureTeam(config2, "junis");
       if (!checked) {
         let waitingPrinted = false;
@@ -2633,7 +2671,10 @@ program.command("start", { isDefault: true }).description("Start Junis agent con
             } else {
               process.stdout.write("\xB7");
             }
-          }
+          },
+          oldDeviceKey,
+          oldToken,
+          oldDeviceKey
         );
         console.log("");
         console.log(` \u2705 Authenticated as ${authResult.email ?? "your account"}`);
@@ -2799,6 +2840,8 @@ program.command("start", { isDefault: true }).description("Start Junis agent con
       console.log("");
     }
   } else {
+    const oldDeviceKey = config.device_key;
+    const oldToken = config.token;
     const checked = await checkEnsureTeam(config, "junis");
     if (!checked) {
       let waitingPrinted = false;
@@ -2819,7 +2862,10 @@ program.command("start", { isDefault: true }).description("Start Junis agent con
           } else {
             process.stdout.write("\xB7");
           }
-        }
+        },
+        oldDeviceKey,
+        oldToken,
+        oldDeviceKey
       );
       console.log("");
       console.log(` \u2705 Authenticated as ${authResult.email ?? "your account"}`);

package/dist/server/mcp.js

@@ -1335,7 +1335,6 @@ var APP_BLACKLIST = /* @__PURE__ */ new Set([
 var consecutiveFailures = 0;
 var MAX_CONSECUTIVE_FAILURES = 2;
 async function peekaboo(args) {
-  consecutiveFailures = 0;
   try {
     const { stdout } = await execa("peekaboo", [...args, "--json-output"]);
     consecutiveFailures = 0;
@@ -1359,10 +1358,10 @@ var DesktopTools = class {
     server.tool(
       "desktop_see",
       [
-        "Capture the macOS Accessibility Tree snapshot for a running application. Returns structured element list with IDs, roles, labels, and positions.",
+        "Capture the macOS Accessibility Tree snapshot for a running application. Returns a structured element list with IDs, roles, labels, and positions.",
         "",
-        "WORKFLOW: Call desktop_see \u2192 find target element \u2192 use its ID in desktop_click or desktop_type.",
-        "Pass the returned snapshotId to subsequent calls for 240x speed improvement (cached lookup vs. full re-scan).",
+        "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).",
         "",
         "SAFETY: Terminal, iTerm, and Finder are blocked. Two consecutive failures trigger an automatic safety stop."
       ].join("\n"),
@@ -1395,15 +1394,15 @@ var DesktopTools = class {
       [
         "Click a macOS UI element by its accessibility label, ID, or x,y coordinates.",
         "",
-        "The 'on' parameter accepts: element label text (e.g. 'Save'), accessibility ID from desktop_see, or coordinates as 'x,y' string.",
-        "For faster interaction, pass the snapshotId from a recent desktop_see call.",
+        "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.",
         "",
         "SAFETY: Terminal, iTerm, and Finder are blocked. Two consecutive failures trigger automatic safety stop."
       ].join("\n"),
       {
         on: z5.string().describe("Element label, accessibility ID, or 'x,y' coordinates to click"),
         app: z5.string().optional().describe("App name to target (e.g. 'Safari')"),
-        snapshot: z5.string().optional().describe("snapshotId from desktop_see for cached interaction (240x faster)"),
+        snapshot: z5.string().optional().describe("snapshotId from a previous accessibility tree capture for cached interaction (240x faster)"),
         doubleClick: z5.boolean().optional().default(false).describe("Double-click instead of single click")
       },
       async ({ on, app, snapshot, doubleClick }) => {
@@ -1423,7 +1422,9 @@ var DesktopTools = class {
       [
         "Type text into the currently focused UI element on macOS. The text is sent as keyboard input character-by-character.",
         "",
-        "SAFETY: Terminal, iTerm, and Finder are blocked. Use desktop_see first to verify the correct element is focused."
+        "IMPORTANT: Always capture the accessibility tree first to verify the correct element is focused before typing.",
+        "",
+        "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
         text: z5.string().describe("Text to type into the focused element"),
@@ -1464,11 +1465,17 @@ var DesktopTools = class {
     );
     server.tool(
       "desktop_scroll",
-      "Scroll within a macOS application or specific UI element. Use 'ticks' to control scroll distance (default: 3). Can target a specific element by label or ID with the 'on' parameter.",
+      [
+        "Scroll within a macOS application or specific UI element.",
+        "",
+        "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.",
+        "",
+        "SAFETY: Terminal, iTerm, and Finder are blocked."
+      ].join("\n"),
       {
         direction: z5.enum(["up", "down", "left", "right"]).describe("Scroll direction"),
         ticks: z5.number().optional().default(3).describe("Number of scroll ticks (default: 3). Higher = more scrolling."),
-        on: z5.string().optional().describe("Element label or ID to scroll within (from desktop_see). Omit to scroll the active area."),
+        on: z5.string().optional().describe("Element label or ID to scroll within (from a previous accessibility tree capture). Omit to scroll the active area."),
         app: z5.string().optional().describe("App name to target")
       },
       async ({ direction, ticks, on, app }) => {
@@ -1484,23 +1491,38 @@ var DesktopTools = class {
     );
     server.tool(
       "desktop_list_apps",
-      "List all currently running applications on macOS. Returns app names that can be used as the 'app' parameter in other desktop tools (desktop_see, desktop_click, desktop_type, etc.).",
+      [
+        "List all currently running applications on macOS. Returns app names usable as the 'app' parameter in all other desktop tools.",
+        "",
+        "WORKFLOW: This is typically the first step \u2014 identify which apps are running before interacting with their UI.",
+        "The returned names are exact strings to pass as 'app' (e.g. 'Safari', 'Google Chrome', 'Notes')."
+      ].join("\n"),
       {},
       async () => {
         try {
           const { stdout } = await execa("peekaboo", ["list", "apps", "--json"]);
+          consecutiveFailures = 0;
           return {
             content: [{ type: "text", text: stdout }]
           };
         } catch (err) {
           consecutiveFailures++;
+          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 err;
         }
       }
     );
     server.tool(
       "desktop_list_windows",
-      "List all open windows on macOS, optionally filtered by app name. If no app is specified, lists windows for the frontmost application. Useful for identifying which windows are available for automation.",
+      [
+        "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."
+      ].join("\n"),
       {
         app: z5.string().optional().describe("Filter by app name. Omit to query the frontmost app.")
       },
@@ -1517,11 +1539,16 @@ var DesktopTools = class {
           }
           const args = ["list", "windows", "--app", targetApp, "--json"];
           const { stdout } = await execa("peekaboo", args);
+          consecutiveFailures = 0;
           return {
             content: [{ type: "text", text: stdout }]
           };
         } catch (err) {
           consecutiveFailures++;
+          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 err;
         }
       }
@@ -1529,10 +1556,12 @@ var DesktopTools = class {
     server.tool(
       "desktop_screenshot",
       [
-        "Take a high-quality macOS screenshot using Peekaboo (Retina display support). Returns base64 image data.",
+        "Take a high-quality macOS screenshot (Retina display support). Returns base64 image data.",
         "",
         "MODES: 'screen' captures the full display, 'window' captures a specific app window.",
-        "Prefer desktop_see (Accessibility Tree) for understanding UI structure \u2014 use screenshot only when visual appearance matters (layouts, images, colors)."
+        "TIP: Prefer the accessibility tree for understanding UI structure \u2014 use screenshots only when visual appearance matters (layouts, images, colors).",
+        "",
+        "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
         app: z5.string().optional().describe("Capture a specific app's window (by name)"),
@@ -1564,10 +1593,12 @@ var DesktopTools = class {
     server.tool(
       "desktop_menu",
       [
-        "Click a menu bar item in a macOS application. Navigate nested menus by adding path segments.",
+        "Click a menu bar item in a macOS application. Navigate nested menus by providing path segments.",
         "",
         "Examples: ['File', 'New Tab'], ['Edit', 'Find', 'Find...'], ['View', 'Enter Full Screen'].",
-        "The target app must be running and accessible."
+        "Omit the 'app' parameter to target the frontmost app. The target app must be running.",
+        "",
+        "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
         path: z5.array(z5.string()).describe("Menu path as array (e.g. ['File', 'Save'], ['Edit', 'Find', 'Find...'])"),
@@ -1579,11 +1610,16 @@ var DesktopTools = class {
         if (app) args.push("--app", app);
         try {
           const { stdout } = await execa("peekaboo", args);
+          consecutiveFailures = 0;
           return {
             content: [{ type: "text", text: stdout || "Menu click executed" }]
           };
         } catch (err) {
           consecutiveFailures++;
+          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 err;
         }
       }

package/package.json

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