crewly 1.2.3 → 1.2.4

package/config/skills/agent/computer-use/execute.sh

@@ -0,0 +1,228 @@
+#!/usr/bin/env bash
+# =============================================================================
+# Agent Browser — Universal Desktop Control
+# Main entry point with subcommands for app discovery, AppleScript,
+# Accessibility API, and Playwright CDP integration.
+#
+# Usage:
+#   bash execute.sh <subcommand> [--options...]
+#
+# Subcommands:
+#   list-apps                 List all controllable GUI apps
+#   app-info   --app NAME     Get detailed app info
+#   ui-tree    --app NAME     Read UI element tree (Accessibility)
+#   click      --app NAME     Click element or coordinates
+#   type       --text TEXT    Type text in focused field
+#   get-text   --app NAME     Extract all text from app
+#   scroll     --app NAME     Scroll within app
+#   focus      --app NAME     Bring app to foreground
+#   screenshot [--app NAME]   Screenshot app or full screen
+#   applescript --code CODE   Run custom AppleScript
+#   applescript --preset NAME Run preset AppleScript
+#   check-access              Check Accessibility permission
+#   chrome-connect [--port N] Connect to Chrome CDP
+#   chrome-tabs    [--port N] List Chrome tabs
+#   chrome-eval    --code JS  Evaluate JS in Chrome tab
+# =============================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LIB_DIR="${SCRIPT_DIR}/lib"
+LOG_DIR="${HOME}/.crewly/logs"
+LOG_FILE="${LOG_DIR}/computer-use.log"
+
+# Source lib files
+source "${LIB_DIR}/discover.sh"
+source "${LIB_DIR}/applescript.sh"
+source "${LIB_DIR}/accessibility.sh"
+source "${LIB_DIR}/screenshot.sh"
+source "${LIB_DIR}/playwright.sh"
+
+# Ensure log directory exists
+mkdir -p "$LOG_DIR"
+
+# -----------------------------------------------------------------------------
+# Logging — all actions are logged for audit trail
+# -----------------------------------------------------------------------------
+log_action() {
+  local timestamp
+  timestamp=$(date '+%Y-%m-%d %H:%M:%S')
+  echo "[$timestamp] $*" >> "$LOG_FILE"
+}
+
+# -----------------------------------------------------------------------------
+# Argument parsing
+# -----------------------------------------------------------------------------
+SUBCOMMAND="${1:-}"
+shift 2>/dev/null || true
+
+# Parse named arguments
+APP_NAME=""
+ELEMENT=""
+TEXT=""
+CODE=""
+PRESET=""
+OUTPUT=""
+DEPTH=""
+DIRECTION=""
+AMOUNT=""
+PORT=""
+TAB=""
+X_COORD=""
+Y_COORD=""
+MENU=""
+ITEM=""
+FILE_PATH=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --app)      shift; APP_NAME="${1:-}" ;;
+    --element)  shift; ELEMENT="${1:-}" ;;
+    --text)     shift; TEXT="${1:-}" ;;
+    --code)     shift; CODE="${1:-}" ;;
+    --preset)   shift; PRESET="${1:-}" ;;
+    --output)   shift; OUTPUT="${1:-}" ;;
+    --depth)    shift; DEPTH="${1:-}" ;;
+    --direction) shift; DIRECTION="${1:-}" ;;
+    --amount)   shift; AMOUNT="${1:-}" ;;
+    --port)     shift; PORT="${1:-}" ;;
+    --tab)      shift; TAB="${1:-}" ;;
+    --x)        shift; X_COORD="${1:-}" ;;
+    --y)        shift; Y_COORD="${1:-}" ;;
+    --menu)     shift; MENU="${1:-}" ;;
+    --item)     shift; ITEM="${1:-}" ;;
+    --path)     shift; FILE_PATH="${1:-}" ;;
+    *)          ;; # Ignore unknown args
+  esac
+  shift 2>/dev/null || true
+done
+
+# Require a subcommand
+if [ -z "$SUBCOMMAND" ]; then
+  cat <<'USAGE'
+Usage: bash execute.sh <subcommand> [--options...]
+
+Subcommands:
+  list-apps                          List all controllable GUI apps
+  app-info      --app NAME           Get detailed app info
+  ui-tree       --app NAME [--depth] Read UI element tree
+  click         --app NAME --element ROLE:NAME  Click by element
+  click         --app NAME --x N --y N          Click by coordinates
+  type          --text TEXT          Type text in focused field
+  get-text      --app NAME           Extract all text from app
+  scroll        --app NAME [--direction up|down] [--amount N]
+  focus         --app NAME           Bring app to foreground
+  screenshot    [--app NAME] [--output PATH]
+  applescript   --code 'CODE'        Run custom AppleScript
+  applescript   --preset NAME --app NAME [--menu M --item I] [--path P]
+  check-access                       Check Accessibility permission
+  chrome-connect [--port N]          Connect to Chrome CDP
+  chrome-tabs    [--port N]          List Chrome tabs
+  chrome-eval    [--port N] [--tab N] --code 'JS'  Evaluate JS in tab
+USAGE
+  exit 1
+fi
+
+# -----------------------------------------------------------------------------
+# Dispatch
+# -----------------------------------------------------------------------------
+case "$SUBCOMMAND" in
+  list-apps)
+    log_action "list-apps"
+    list_apps
+    ;;
+
+  app-info)
+    [ -z "$APP_NAME" ] && { echo '{"error":"Missing --app parameter"}' >&2; exit 1; }
+    log_action "app-info app=$APP_NAME"
+    app_info "$APP_NAME"
+    ;;
+
+  ui-tree)
+    [ -z "$APP_NAME" ] && { echo '{"error":"Missing --app parameter"}' >&2; exit 1; }
+    log_action "ui-tree app=$APP_NAME depth=${DEPTH:-8}"
+    ui_tree "$APP_NAME" "${DEPTH:-8}"
+    ;;
+
+  click)
+    [ -z "$APP_NAME" ] && { echo '{"error":"Missing --app parameter"}' >&2; exit 1; }
+    log_action "click app=$APP_NAME element=${ELEMENT:-} x=${X_COORD:-} y=${Y_COORD:-}"
+    click_element "$APP_NAME" "$ELEMENT" "$X_COORD" "$Y_COORD"
+    ;;
+
+  type)
+    [ -z "$TEXT" ] && { echo '{"error":"Missing --text parameter"}' >&2; exit 1; }
+    log_action "type chars=${#TEXT}"
+    type_text "$TEXT"
+    ;;
+
+  get-text)
+    [ -z "$APP_NAME" ] && { echo '{"error":"Missing --app parameter"}' >&2; exit 1; }
+    log_action "get-text app=$APP_NAME depth=${DEPTH:-25}"
+    get_text "$APP_NAME" "${DEPTH:-25}"
+    ;;
+
+  scroll)
+    log_action "scroll app=${APP_NAME:-focused} direction=${DIRECTION:-down} amount=${AMOUNT:-3}"
+    scroll_app "${DIRECTION:-down}" "${AMOUNT:-3}" "$APP_NAME"
+    ;;
+
+  focus)
+    [ -z "$APP_NAME" ] && { echo '{"error":"Missing --app parameter"}' >&2; exit 1; }
+    log_action "focus app=$APP_NAME"
+    focus_app "$APP_NAME"
+    ;;
+
+  screenshot)
+    log_action "screenshot app=${APP_NAME:-full-screen} output=${OUTPUT:-/tmp/screenshot.png}"
+    take_screenshot "${OUTPUT:-/tmp/screenshot.png}" "$APP_NAME"
+    ;;
+
+  applescript)
+    if [ -n "$PRESET" ]; then
+      log_action "applescript preset=$PRESET app=${APP_NAME:-} menu=${MENU:-} item=${ITEM:-} path=${FILE_PATH:-}"
+      case "$PRESET" in
+        activate-app)   run_preset "activate-app" "$APP_NAME" ;;
+        get-window-list) run_preset "get-window-list" "$APP_NAME" ;;
+        click-menu-item) run_preset "click-menu-item" "$APP_NAME" "$MENU" "$ITEM" ;;
+        open-file)       run_preset "open-file" "$FILE_PATH" ;;
+        get-clipboard)   run_preset "get-clipboard" ;;
+        set-clipboard)   run_preset "set-clipboard" "$TEXT" ;;
+        *)              echo '{"error":"Unknown preset: '"$PRESET"'"}' >&2; exit 1 ;;
+      esac
+    elif [ -n "$CODE" ]; then
+      log_action "applescript custom-code"
+      run_applescript "$CODE"
+    else
+      echo '{"error":"Missing --code or --preset parameter"}' >&2
+      exit 1
+    fi
+    ;;
+
+  check-access)
+    log_action "check-access"
+    do_check_access
+    ;;
+
+  chrome-connect)
+    log_action "chrome-connect port=${PORT:-9222}"
+    chrome_connect "${PORT:-9222}"
+    ;;
+
+  chrome-tabs)
+    log_action "chrome-tabs port=${PORT:-9222}"
+    chrome_tabs "${PORT:-9222}"
+    ;;
+
+  chrome-eval)
+    [ -z "$CODE" ] && { echo '{"error":"Missing --code parameter"}' >&2; exit 1; }
+    log_action "chrome-eval port=${PORT:-9222} tab=${TAB:-0}"
+    chrome_eval "${PORT:-9222}" "${TAB:-0}" "$CODE"
+    ;;
+
+  *)
+    echo "{\"error\":\"Unknown subcommand: $SUBCOMMAND\"}" >&2
+    exit 1
+    ;;
+esac

package/config/skills/agent/computer-use/instructions.md

@@ -0,0 +1,103 @@
+# Agent Browser — Universal Desktop Control
+
+Control any macOS application through three integrated methods: AppleScript/JXA, Accessibility API, and Playwright CDP.
+
+## Quick Reference
+
+```bash
+# List all controllable apps with available methods
+bash execute.sh list-apps
+
+# Get app info with UI element tree
+bash execute.sh app-info --app 'Google Chrome'
+
+# Read UI tree of an app (Accessibility API)
+bash execute.sh ui-tree --app 'Finder' --depth 5
+
+# Click a UI element by role:name
+bash execute.sh click --app 'Finder' --element 'button:New Folder'
+
+# Click at coordinates
+bash execute.sh click --app 'Finder' --x 500 --y 300
+
+# Type text in focused app
+bash execute.sh type --text 'Hello World'
+
+# Screenshot an app window
+bash execute.sh screenshot --app 'Notion' --output /tmp/notion.png
+
+# Screenshot full screen
+bash execute.sh screenshot --output /tmp/screen.png
+
+# Run custom AppleScript
+bash execute.sh applescript --code 'tell application "Finder" to get name of every window'
+
+# Run common AppleScript presets
+bash execute.sh applescript --preset activate-app --app 'Safari'
+bash execute.sh applescript --preset get-window-list --app 'Finder'
+bash execute.sh applescript --preset click-menu-item --app 'Safari' --menu 'File' --item 'New Window'
+bash execute.sh applescript --preset open-file --path '/Users/me/doc.txt'
+
+# Extract all text from an app
+bash execute.sh get-text --app 'Notes'
+
+# Scroll in an app
+bash execute.sh scroll --app 'Safari' --direction down --amount 5
+
+# Focus (activate) an app
+bash execute.sh focus --app 'Terminal'
+
+# Check accessibility permission
+bash execute.sh check-access
+
+# Connect to Chrome via CDP
+bash execute.sh chrome-connect --port 9222
+
+# Chrome: list tabs
+bash execute.sh chrome-tabs --port 9222
+
+# Chrome: run JS in a tab
+bash execute.sh chrome-eval --port 9222 --tab 0 --code 'document.title'
+```
+
+## Control Methods
+
+### Layer 1: App Discovery
+- `list-apps` — Lists all foreground apps with bundle IDs and available control methods
+- `app-info` — Gets detailed info: windows, UI elements, controllability
+
+### Layer 2: AppleScript/JXA (native macOS apps)
+- `applescript` — Run custom AppleScript or use presets
+- Presets: `activate-app`, `get-window-list`, `click-menu-item`, `open-file`, `get-clipboard`, `set-clipboard`
+- Works with: Finder, Terminal, Safari, Mail, Calendar, Notes, Sublime Text, etc.
+
+### Layer 3: Accessibility API (universal)
+- `ui-tree` — Read any app's UI element tree (roles, titles, values, positions)
+- `click` — Click elements by role:name or coordinates
+- `type` — Type text in the focused field
+- `get-text` — Extract all visible text from an app
+- `scroll` — Scroll within an app
+- `focus` — Bring an app to the foreground
+- `screenshot` — Capture app window or full screen
+- Requires: System Settings > Privacy & Security > Accessibility permission
+
+### Layer 4: Playwright CDP (Chrome web apps)
+- `chrome-connect` — Connect to Chrome via Chrome DevTools Protocol
+- `chrome-tabs` — List open Chrome tabs
+- `chrome-eval` — Run JavaScript in a Chrome tab
+- Requires: Chrome launched with `--remote-debugging-port=9222`
+
+## Safety Rules
+
+1. NEVER close or kill apps without explicit user permission
+2. NEVER interact with password fields or sensitive data
+3. Always screenshot BEFORE and AFTER any action for audit trail
+4. All actions logged to `~/.crewly/logs/computer-use.log`
+5. iPad apps: READ ONLY via Accessibility — never killall, never force-quit
+
+## Requirements
+
+- macOS (Apple Silicon or Intel)
+- `jq` for JSON parsing
+- Accessibility permission for UI reading/interaction
+- Chrome with `--remote-debugging-port` for CDP features

package/config/skills/agent/computer-use/lib/accessibility.sh

@@ -0,0 +1,292 @@
+#!/usr/bin/env bash
+# =============================================================================
+# Accessibility API — Layer 3
+# Universal UI automation: read elements, click, type, scroll, focus.
+# =============================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../../_common/lib.sh"
+
+# -----------------------------------------------------------------------------
+# Accessibility permission check (cached per invocation)
+# -----------------------------------------------------------------------------
+_AX_CHECKED=""
+_AX_TRUSTED=""
+
+check_ax_permission() {
+  if [ -z "$_AX_CHECKED" ]; then
+    _AX_TRUSTED=$(swift -e 'import Cocoa; print(AXIsProcessTrusted())' 2>/dev/null || echo "false")
+    _AX_CHECKED="1"
+  fi
+  [ "$_AX_TRUSTED" = "true" ]
+}
+
+require_ax_permission() {
+  if ! check_ax_permission; then
+    error_exit "Accessibility permission required. Fix: System Settings > Privacy & Security > Accessibility > enable your terminal app, then restart terminal."
+  fi
+}
+
+do_check_access() {
+  if check_ax_permission; then
+    echo "{\"success\":true,\"action\":\"check-access\",\"trusted\":true,\"message\":\"Accessibility permission granted.\"}"
+  else
+    echo "{\"success\":true,\"action\":\"check-access\",\"trusted\":false,\"message\":\"Accessibility permission NOT granted. Fix: System Settings > Privacy & Security > Accessibility > enable your terminal app.\"}"
+  fi
+}
+
+# -----------------------------------------------------------------------------
+# ui_tree — Read UI element tree from an app
+# Params: appName, maxDepth (default 8)
+# -----------------------------------------------------------------------------
+ui_tree() {
+  local app_name="$1"
+  local max_depth="${2:-8}"
+  require_ax_permission
+
+  local result
+  result=$(osascript -l JavaScript -e "
+    var app = Application('System Events');
+    var proc = app.processes.byName('$app_name');
+    var maxDepth = $max_depth;
+    var nodeCount = 0;
+    var MAX_NODES = 500;
+
+    function readElement(el, depth) {
+      if (depth > maxDepth || nodeCount >= MAX_NODES) return null;
+      nodeCount++;
+      var info = {};
+      try { info.role = el.role(); } catch(e) { info.role = 'unknown'; }
+      try { var t = el.title(); if (t) info.title = t; } catch(e) {}
+      try { var v = el.value(); if (v !== null && v !== undefined) info.value = String(v).substring(0, 500); } catch(e) {}
+      try { var d = el.description(); if (d) info.description = d; } catch(e) {}
+      try { var p = el.position(); info.position = {x: p[0], y: p[1]}; } catch(e) {}
+      try { var s = el.size(); info.size = {w: s[0], h: s[1]}; } catch(e) {}
+
+      if (depth < maxDepth && nodeCount < MAX_NODES) {
+        try {
+          var children = el.uiElements();
+          if (children.length > 0) {
+            info.children = [];
+            for (var i = 0; i < Math.min(children.length, 50); i++) {
+              var child = readElement(children[i], depth + 1);
+              if (child) info.children.push(child);
+            }
+          }
+        } catch(e) {}
+      }
+      return info;
+    }
+
+    var windows = proc.windows();
+    var result = {windowCount: windows.length, windows: []};
+    for (var w = 0; w < windows.length; w++) {
+      var win = windows[w];
+      var winInfo = readElement(win, 0);
+      try { winInfo.windowTitle = win.title() || win.name() || 'Window ' + w; } catch(e) { winInfo.windowTitle = 'Window ' + w; }
+      result.windows.push(winInfo);
+    }
+    JSON.stringify(result);
+  " 2>&1)
+
+  if [ $? -ne 0 ]; then
+    error_exit "Failed to read UI tree for '$app_name': $result"
+  fi
+  echo "{\"success\":true,\"action\":\"ui-tree\",\"appName\":\"$app_name\",\"maxDepth\":$max_depth,\"ui\":$result}"
+}
+
+# -----------------------------------------------------------------------------
+# click_element — Click a UI element by role:name or coordinates
+# Params: appName, element (role:name) OR x,y
+# -----------------------------------------------------------------------------
+click_element() {
+  local app_name="$1"
+  local element="${2:-}"
+  local click_x="${3:-}"
+  local click_y="${4:-}"
+
+  if [ -n "$element" ]; then
+    # Parse role:name format
+    local role name
+    role=$(echo "$element" | cut -d: -f1)
+    name=$(echo "$element" | cut -d: -f2-)
+
+    # Find element position via Accessibility API
+    require_ax_permission
+    local pos
+    pos=$(osascript -l JavaScript -e "
+      var app = Application('System Events');
+      var proc = app.processes.byName('$app_name');
+      var found = null;
+
+      function findElement(el, depth) {
+        if (depth > 10 || found) return;
+        var elRole = '';
+        var elTitle = '';
+        var elDesc = '';
+        try { elRole = el.role(); } catch(e) {}
+        try { elTitle = el.title() || ''; } catch(e) {}
+        try { elDesc = el.description() || ''; } catch(e) {}
+
+        var roleMatch = '$role' === '' || elRole.toLowerCase().indexOf('$role'.toLowerCase()) >= 0;
+        var nameMatch = elTitle.indexOf('$name') >= 0 || elDesc.indexOf('$name') >= 0;
+
+        if (roleMatch && nameMatch) {
+          try {
+            var p = el.position();
+            var s = el.size();
+            found = {x: p[0] + s[0]/2, y: p[1] + s[1]/2};
+          } catch(e) {}
+        }
+
+        if (!found) {
+          try {
+            var children = el.uiElements();
+            for (var i = 0; i < children.length && !found; i++) {
+              findElement(children[i], depth + 1);
+            }
+          } catch(e) {}
+        }
+      }
+
+      var windows = proc.windows();
+      for (var w = 0; w < windows.length && !found; w++) {
+        findElement(windows[w], 0);
+      }
+      found ? JSON.stringify(found) : 'null';
+    " 2>&1)
+
+    if [ "$pos" = "null" ] || [ -z "$pos" ]; then
+      error_exit "Element '$element' not found in '$app_name'"
+    fi
+
+    click_x=$(echo "$pos" | jq -r '.x')
+    click_y=$(echo "$pos" | jq -r '.y')
+  fi
+
+  require_param "x or element" "$click_x"
+  require_param "y or element" "$click_y"
+
+  # Perform the click via CoreGraphics
+  osascript -l JavaScript -e "
+    ObjC.import('CoreGraphics');
+    var point = $.CGPointMake($click_x, $click_y);
+    var move = $.CGEventCreateMouseEvent(null, $.kCGEventMouseMoved, point, 0);
+    $.CGEventPost($.kCGHIDEventTap, move);
+    var down = $.CGEventCreateMouseEvent(null, $.kCGEventLeftMouseDown, point, 0);
+    $.CGEventPost($.kCGHIDEventTap, down);
+    var up = $.CGEventCreateMouseEvent(null, $.kCGEventLeftMouseUp, point, 0);
+    $.CGEventPost($.kCGHIDEventTap, up);
+    'clicked';
+  " >/dev/null 2>&1
+
+  echo "{\"success\":true,\"action\":\"click\",\"appName\":\"$app_name\",\"x\":$click_x,\"y\":$click_y,\"element\":\"${element:-coordinates}\"}"
+}
+
+# -----------------------------------------------------------------------------
+# type_text — Type text in the focused field
+# Params: text
+# -----------------------------------------------------------------------------
+type_text() {
+  local text="$1"
+  osascript -e "tell application \"System Events\" to keystroke \"$text\"" 2>/dev/null
+  local char_count=${#text}
+  echo "{\"success\":true,\"action\":\"type\",\"characters\":$char_count}"
+}
+
+# -----------------------------------------------------------------------------
+# get_text — Extract all visible text from an app
+# Params: appName, maxDepth (default 25)
+# -----------------------------------------------------------------------------
+get_text() {
+  local app_name="$1"
+  local max_depth="${2:-25}"
+  require_ax_permission
+
+  local result
+  result=$(osascript -l JavaScript -e "
+    var app = Application('System Events');
+    var proc = app.processes.byName('$app_name');
+    var texts = [];
+    var maxDepth = $max_depth;
+    var skipDescs = {'group':1,'button':1,'scroll area':1,'collection':1,'text':1,
+      'standard window':1,'image':1,'tab bar':1,'close button':1,
+      'full screen button':1,'minimize button':1};
+
+    function extractText(el, depth) {
+      if (depth > maxDepth) return;
+      var role = 'unknown';
+      try { role = el.role(); } catch(e) {}
+      try { var val = el.value(); if (val !== null && val !== undefined && String(val).trim().length > 0) texts.push({role: role, text: String(val).substring(0, 1000)}); } catch(e) {}
+      try { var title = el.title(); if (title && title.trim().length > 0) texts.push({role: role, text: title}); } catch(e) {}
+      try { var desc = el.description(); if (desc && desc.trim().length > 0 && !skipDescs[desc.toLowerCase()]) texts.push({role: role, text: desc}); } catch(e) {}
+      try { var children = el.uiElements(); for (var i = 0; i < Math.min(children.length, 100); i++) extractText(children[i], depth + 1); } catch(e) {}
+    }
+
+    var windows = proc.windows();
+    for (var w = 0; w < windows.length; w++) extractText(windows[w], 0);
+
+    var seen = {};
+    var unique = [];
+    for (var i = 0; i < texts.length; i++) {
+      if (!seen[texts[i].text]) { seen[texts[i].text] = true; unique.push(texts[i]); }
+    }
+    JSON.stringify(unique);
+  " 2>&1)
+
+  if [ $? -ne 0 ]; then
+    error_exit "Failed to get text from '$app_name': $result"
+  fi
+  echo "{\"success\":true,\"action\":\"get-text\",\"appName\":\"$app_name\",\"texts\":$result}"
+}
+
+# -----------------------------------------------------------------------------
+# scroll_app — Scroll within an app
+# Params: direction (up|down|left|right), amount (default 3), appName (optional)
+# -----------------------------------------------------------------------------
+scroll_app() {
+  local direction="${1:-down}"
+  local amount="${2:-3}"
+  local app_name="${3:-}"
+
+  if [ -n "$app_name" ]; then
+    osascript -l JavaScript -e "
+      var app = Application('System Events');
+      app.processes.byName('$app_name').frontmost = true;
+    " >/dev/null 2>&1
+    sleep 0.3
+  fi
+
+  local dx=0 dy=0
+  case "$direction" in
+    up)    dy=$amount ;;
+    down)  dy=$(( -amount )) ;;
+    left)  dx=$amount ;;
+    right) dx=$(( -amount )) ;;
+    *)     error_exit "Unknown direction: $direction" ;;
+  esac
+
+  osascript -l JavaScript -e "
+    ObjC.import('CoreGraphics');
+    var event = $.CGEventCreateScrollWheelEvent(null, $.kCGScrollEventUnitLine, 2, $dy, $dx);
+    $.CGEventPost($.kCGHIDEventTap, event);
+    'scrolled';
+  " >/dev/null 2>&1
+
+  echo "{\"success\":true,\"action\":\"scroll\",\"direction\":\"$direction\",\"amount\":$amount}"
+}
+
+# -----------------------------------------------------------------------------
+# focus_app — Bring an app to the foreground
+# Params: appName
+# -----------------------------------------------------------------------------
+focus_app() {
+  local app_name="$1"
+  osascript -l JavaScript -e "
+    var app = Application('System Events');
+    app.processes.byName('$app_name').frontmost = true;
+  " >/dev/null 2>&1
+  echo "{\"success\":true,\"action\":\"focus\",\"appName\":\"$app_name\"}"
+}