arena-bridge 0.6.2 → 0.6.4

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to this project are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/) and the project uses
 [Semantic Versioning](https://semver.org/).
 
+## 0.6.4
+
+### Fixed
+- The accessibility element map is read from Peekaboo's real payload (`data.ui_elements`), so
+  `mac_see` and `mac_element` now return the controls of a window instead of an empty list.
+  Elements carry their label, description, identifier and value-settable flag.
+- Commands follow the Peekaboo v4 grammar: `set-value "<value>" --on <id>`, `menu click --item|--path`
+  with an explicit app, `space switch --to <n> --foreground`, and the tree-only read
+  `see --tree --no-screenshot --json` (no screenshot artifact for pure lookups).
+
+## 0.6.3
+
+### Added
+- Desktop control now works through the macOS accessibility API first, not by pixel guessing:
+  - `mac_element` finds a control by its visible name, role or value and returns its id;
+  - `mac_set` writes a value straight into a control — no keystrokes, no focus change;
+  - `mac_menu` / `mac_menu_click` list and trigger menu items by name;
+  - `mac_wait` waits until a control appears or disappears instead of sleeping;
+  - `mac_spaces` / `mac_space_switch` move the agent to another macOS Space (virtual desktop).
+- `mac_see` asks for the accessibility element map explicitly and explains what to do when the
+  element list is empty (missing Accessibility permission).
+
 ## 0.6.2
 
 ### Added

package/README.md

@@ -12,7 +12,7 @@
   <img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="license">
   <img src="https://img.shields.io/badge/node-%3E%3D18-green.svg?style=flat-square" alt="node">
   <img src="https://img.shields.io/badge/dependencies-0-brightgreen.svg?style=flat-square" alt="dependencies">
-  <img src="https://img.shields.io/badge/tests-96%20passed-brightgreen.svg?style=flat-square" alt="tests">
+  <img src="https://img.shields.io/badge/tests-110%20passed-brightgreen.svg?style=flat-square" alt="tests">
 </p>
 
 <p align="center">
@@ -82,7 +82,7 @@ arena-bridge setup --root ~/projects
 | Шелл | `bash` `sysinfo` | команды и сведения о машине |
 | Процессы | `start_process` `read_process_output` `write_process` `kill_process` | фоновые дев-серверы |
 | Chrome | `chrome_launch` `chrome_profiles` `chrome_attach` `chrome_open` `chrome_navigate` `chrome_snapshot` `chrome_click` `chrome_type` `chrome_press` `chrome_screenshot` `chrome_evaluate` `chrome_tabs` `chrome_stop` | браузер через CDP |
-| Десктоп | `mac_see` `mac_click` `mac_type` `mac_key` `mac_scroll` `mac_move` `mac_drag` `mac_apps` `mac_windows` `mac_app_launch` `mac_app_focus` `mac_app_quit` `mac_permissions` | macOS через Peekaboo |
+| Десктоп | `mac_see` `mac_element` `mac_click` `mac_set` `mac_type` `mac_key` `mac_scroll` `mac_move` `mac_drag` `mac_menu` `mac_menu_click` `mac_wait` `mac_spaces` `mac_space_switch` `mac_apps` `mac_windows` `mac_app_launch` `mac_app_focus` `mac_app_quit` `mac_permissions` | macOS через Peekaboo |
 
 Полный каталог с JSON-схемами: `GET /tools` или `arena-bridge tools`.
 
@@ -93,7 +93,11 @@ arena-bridge setup --root ~/projects
 | прочитать страницу | `chrome_snapshot` (`{"mode":"ax"}` — роли и имена, `{"mode":"text"}`, `{"mode":"html"}`) |
 | кликнуть на странице | `chrome_click` (CSS-селектор или видимый текст) |
 | работать в вашем залогиненном Chrome | `chrome_attach` (порт 9222) и те же `chrome_*` |
-| посмотреть на экран или нативное приложение | `mac_see` (скриншот + id кликабельных элементов) |
+| посмотреть на экран или нативное приложение | `mac_see` (скриншот + id элементов) |
+| найти контрол по названию, без скриншота | `mac_element` (через Accessibility API: имя, роль, значение) |
+| заполнить поле, не печатая и не забирая фокус | `mac_set` (значение пишется напрямую в элемент) |
+| открыть пункт меню | `mac_menu` (список) → `mac_menu_click` (по названию) |
+| дождаться, пока контрол появится | `mac_wait` |
 | кликнуть в нативном приложении | `mac_click` (id элемента, видимый текст или координаты) |
 | напечатать | `mac_type`, затем `mac_key` для Enter/Tab/cmd+s |
 | посмотреть файлы | `list_dir` (только верхний уровень; глубже — `{"recursive":true}`) |
@@ -141,9 +145,13 @@ cookies и localStorage нет.
 
 ```jsonc
 {"tool": "mac_see", "args": {"app": "Safari", "mode": "window"}}  // скриншот + id элементов
-{"tool": "mac_click", "args": {"on": "B3"}}                        // клик по id из mac_see
+{"tool": "mac_element", "args": {"name": "Save"}}                // найти кнопку по названию
+{"tool": "mac_click", "args": {"on": "B3"}}                      // клик по id из mac_see
+{"tool": "mac_set", "args": {"on": "B2", "value": "hello"}}      // вписать значение напрямую
 {"tool": "mac_type", "args": {"text": "hello", "submit": true}}
 {"tool": "mac_key", "args": {"key": "cmd+s"}}
+{"tool": "mac_menu_click", "args": {"app": "Safari", "item": "Save"}}  // пункт меню по названию
+{"tool": "mac_wait", "args": {"name": "Saved", "timeout": 20}}        // дождаться результата
 {"tool": "mac_apps", "args": {}}                                  // что запущено
 {"tool": "mac_permissions", "args": {}}                           // чего не хватает в macOS
 ```
@@ -152,6 +160,26 @@ cookies и localStorage нет.
 macOS спросит разрешения **Screen Recording** и **Accessibility** для терминала, из которого
 запущен мост — без них скриншоты и клики не работают; `mac_permissions` покажет, что не так.
 
+### Что даёт доступ Accessibility
+
+macOS отдаёт приложениям два разных слоя: картинку экрана и **Accessibility API** — дерево
+элементов интерфейса с названиями, ролями и значениями. Второй слой полезен агенту сильнее:
+
+| | по картинке | через Accessibility API |
+| --- | --- | --- |
+| как найти кнопку «Сохранить» | угадать координаты | `mac_element {"name":"Сохранить"}` → точный элемент |
+| как нажать | клик по координате, может промахнуться | `mac_click {"on":"<id>"}` — по самому элементу |
+| как вписать текст | свайп, фокус, клавиатура | `mac_set {"on":"<id>","value":"..."}` — без фокуса и без клавиш |
+| как открыть «Файл → Экспорт» | перемещать курсор по меню | `mac_menu_click {"item":"Экспорт"}` — по названию |
+| как убедиться, что получилось | смотреть скриншот | `mac_wait {"name":"Готово"}` — ждать появления |
+| как заполнить поле | свайп + клавиатура + фокус | `mac_set {"on":"<id>","value":"..."}` — значение пишется в элемент |
+| чужой ввод и фокус | мешает вам | действия уходят в фоновое окно |
+
+Практический вывод: с выданным Accessibility агент работает заметно точнее и тише. Разрешение
+даётся один раз в **Системные настройки → Конфиденциальность и безопасность → Универсальный
+доступ** (для терминала, из которого запущен мост). `mac_permissions` показывает текущее
+состояние разрешений.
+
 ---
 
 ## Доверенное окно: работать без подтверждений
@@ -199,7 +227,7 @@ arena-bridge browser close work       # закрыть окно этого пр
 | --- | --- |
 | окно агента занимает экран | по умолчанию агент работает в фоне; видимое окно можно сделать маленьким и в углу: `chrome_launch {"headless":false,"width":900,"height":700,"x":-920,"y":40}` |
 | агент перехватывает фокус и курсор | действия в нативных приложениях идут «в фон» — в нужное окно, без переключения на вас; курсор двигается только по вашей явной просьбе |
-| окно агента на вашем рабочем столе | macOS умеет несколько рабочих столов: окно агента живёт на отдельном столе, вы — на своём |
+| окно агента на вашем рабочем столе | macOS умеет несколько рабочих столов: агент переключается на отдельный стол через `mac_space_switch`, вы остаётесь на своём |
 | нужен отдельный «второй монитор» | в macOS виртуальный монитор штатно не создаётся; сторонние утилиты (BetterDisplay, DisplayLink) умеют — тогда окно агента всегда там, где вы не работаете |
 | нужен полностью независимый курсор и стол | только отдельная виртуальная машина; на 16 ГБ и Intel 2019 года она заметно тормозит и съедает 30–60 ГБ — как правило, не нужно |
 
@@ -295,8 +323,8 @@ npm run test:python  # 44 теста Python: то же самое
 src/            Node-реализация (zero dependencies)
   ws.mjs        минимальный WebSocket-клиент
   cdp.mjs       клиент Chrome DevTools Protocol
-  browser.mjs   12 инструментов chrome_*
-  mac.mjs       13 инструментов mac_* (Peekaboo)
+  browser.mjs   13 инструментов chrome_*
+  mac.mjs       20 инструментов mac_* (Peekaboo, Accessibility API)
   trust.mjs     окно доверия
   policy.mjs    проверка путей (roots / protected)
   engine.mjs    каталог, гейт подтверждений, аудит

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arena-bridge",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Give a cloud AI agent (Arena.ai Agent Mode, Claude, Cursor, ...) controlled access to your own machine over HTTP/MCP: files, shell, Chrome and the macOS desktop, with an approval gate, trust windows and an audit log.",
   "type": "module",
   "bin": {

package/src/direct.mjs

@@ -29,7 +29,7 @@ export function createDirectServer(cfg, engine) {
           ok: true,
           mode: 'direct',
           device: cfg.device,
-          version: '0.6.2',
+          version: '0.6.4',
           uptime_sec: Math.round(process.uptime()),
         });
       }

package/src/hub.mjs

@@ -90,7 +90,7 @@ export function createHubServer(cfg) {
         return sendJson(res, 200, {
           ok: true,
           mode: 'hub',
-          version: '0.6.2',
+          version: '0.6.4',
           devices: [...devices.keys()],
         });
       }

package/src/mac.mjs

@@ -100,21 +100,31 @@ function parseJson(text) {
 }
 
 function collectElements(node, out = [], depth = 0) {
-  if (!node || depth > 6) return out;
+  if (!node || depth > 8) return out;
   if (Array.isArray(node)) {
     for (const n of node) collectElements(n, out, depth + 1);
     return out;
   }
   if (typeof node !== 'object') return out;
-  if (node.elements && Array.isArray(node.elements)) {
-    for (const e of node.elements) {
+  for (const key of ['ui_elements', 'elements']) {
+    const list = node[key];
+    if (!Array.isArray(list) || !list.length) continue;
+    for (const e of list) {
+      if (!e || typeof e !== 'object') continue;
+      const value = e.value;
       out.push({
-        id: e.id ?? e.elementId ?? e.element_id ?? null,
-        role: e.role ?? e.elementRole ?? e.type ?? null,
+        id: e.id ?? e.element_id ?? e.elementId ?? null,
+        role: e.role ?? e.ax_role ?? e.elementRole ?? e.type ?? null,
         title: e.title ?? e.label ?? e.name ?? e.placeholder ?? null,
-        value: typeof e.value === 'string' ? e.value.slice(0, 200) : null,
-        bounds: e.frame ?? e.bounds ?? e.rect ?? null,
-        enabled: e.enabled ?? null,
+        label: e.label ?? null,
+        description: e.description ?? null,
+        identifier: e.identifier ?? null,
+        value: typeof value === 'string' ? value.slice(0, 200) : (value ?? null),
+        bounds: e.bounds ?? e.frame ?? e.rect ?? null,
+        enabled: e.is_enabled ?? e.enabled ?? null,
+        actionable: e.is_actionable ?? null,
+        settable: e.is_value_settable ?? null,
+        shortcut: e.keyboard_shortcut ?? null,
       });
     }
     return out;
@@ -175,6 +185,53 @@ export function macTools(cfg = {}) {
     return f;
   };
 
+  const seeVariants = (args, outPath) => {
+    const mode = args.mode === 'window' ? 'window' : 'screen';
+    const base = ['see', '--mode', mode, ...targetFlags(args)];
+    if (!outPath) {
+      return [
+        ['see', '--tree', '--no-screenshot', '--json', ...targetFlags(args)],
+        ['see', '--tree', '--json', ...targetFlags(args)],
+        ['see', '--json', ...targetFlags(args)],
+      ];
+    }
+    return [
+      [...base, '--json', '--path', outPath],
+      [...base, '--path', outPath, '--json'],
+      ['image', '--mode', mode, ...targetFlags(args), '--json', '--path', outPath],
+    ];
+  };
+
+  const collectSee = async (args, outPath) => {
+    let best = null;
+    for (const variant of seeVariants(args, outPath)) {
+      const res = await run(peek(), variant, { timeout: 60 });
+      const json = parseJson(res.stdout);
+      const cand = { res, json, elements: collectElements(json), variant };
+      if (!best) best = cand;
+      if (res.exit_code === 0 && cand.elements.length) return cand;
+      if (res.exit_code === 0 && best.res.exit_code !== 0) best = cand;
+      if (res.exit_code !== 0 && !UNKNOWN.test(res.stderr || '')) break;
+    }
+    return best;
+  };
+
+  const matchElement = (e, args) => {
+    const q = (v) => String(v ?? '').toLowerCase();
+    const text = [e.title, e.label, e.description, e.identifier, e.value, e.id]
+      .map(q)
+      .join('\n');
+    if (args.name && !text.includes(q(args.name))) return false;
+    if (args.role && !q(e.role).includes(q(args.role))) return false;
+    if (args.value && !q(e.value).includes(q(args.value))) return false;
+    return true;
+  };
+
+  const searchPath = () => path.join(os.tmpdir(), 'arena-bridge-see', 'see.png');
+
+  const searchSee = (args) =>
+    collectSee({ app: args.app, window_title: args.window_title, mode: args.mode || 'screen' }, null);
+
   return [
     {
       name: 'mac_see',
@@ -199,15 +256,8 @@ export function macTools(cfg = {}) {
         const outPath = args.path ? checkPath(String(args.path), cfg, ctx.base) : { ok: true, abs: defaultShotPath(cfg) };
         if (!outPath.ok) return { ok: false, error: outPath.error, reason: outPath.reason };
         ensureDir(path.dirname(outPath.abs));
-        const mode = args.mode === 'window' ? 'window' : 'screen';
-        const variants = [
-          ['see', '--mode', mode, ...targetFlags(args), '--json', '--path', outPath.abs],
-          ['see', '--mode', mode, ...targetFlags(args), '--path', outPath.abs, '--json'],
-          ['image', '--mode', mode, ...targetFlags(args), '--json', '--path', outPath.abs],
-        ];
-        const res = await runVariants(p.bin, variants, { timeout: 60 });
-        const json = parseJson(res.stdout);
-        const elements = collectElements(json).slice(0, 300);
+        const seen = await collectSee(args, outPath.abs);
+        const elements = seen.elements.slice(0, 300);
         const saved = fs.existsSync(outPath.abs);
         if (!saved) {
           const fb = await captureScreenFallback(outPath.abs);
@@ -215,7 +265,7 @@ export function macTools(cfg = {}) {
             return {
               ok: false,
               error: 'capture_failed',
-              reason: (res.stderr || '').trim().slice(0, 800),
+              reason: (seen.res.stderr || '').trim().slice(0, 800),
               hint: 'Grant Screen Recording permission to the app that runs the bridge (System Settings → Privacy & Security → Screen Recording).',
             };
           }
@@ -226,9 +276,12 @@ export function macTools(cfg = {}) {
           saved,
           elements,
           element_count: elements.length,
-          hint: 'Click by element id: mac_click {"on":"<id>"} or by visible text: mac_click {"text":"Save"}',
+          hint: 'Click by element id: mac_click {"on":"<id>"} or by visible text: mac_click {"text":"Save"}. Find elements by name with mac_element.',
         };
-        if (args.include_raw && json) out.raw = json;
+        if (!elements.length) {
+          out.hint += ' No elements found — run mac_permissions: the element list comes from the macOS Accessibility API.';
+        }
+        if (args.include_raw && seen.json) out.raw = seen.json;
         return out;
       },
     },
@@ -517,6 +570,227 @@ export function macTools(cfg = {}) {
         return finish(res, 'quit');
       },
     },
+    {
+      name: 'mac_element',
+      description:
+        'Find interface elements by visible name, role or value through the macOS accessibility API. No screenshots, no pixel guessing. Read-only.',
+      approval: false,
+      schema: S(
+        {
+          name: { type: 'string', description: 'visible text or title to look for' },
+          role: { type: 'string', description: 'e.g. button, textField, menuItem, staticText' },
+          value: { type: 'string' },
+          app: { type: 'string' },
+          window_title: { type: 'string' },
+          limit: { type: 'number' },
+        },
+        [],
+      ),
+      required: [],
+      handler: async (args) => {
+        const p = checkPeek(peek());
+        if (!p.ok) return p;
+        const seen = await searchSee(args);
+        const matches = seen.elements.filter((e) => matchElement(e, args)).slice(0, Number(args.limit) || 25);
+        return {
+          ok: true,
+          matches,
+          count: matches.length,
+          scanned: seen.elements.length,
+          hint: 'Act on a match by id: mac_click {"on":"<id>"} or mac_set {"on":"<id>","value":"..."}.',
+        };
+      },
+    },
+    {
+      name: 'mac_set',
+      description:
+        'Set the value of an element directly through the accessibility API — fills a field without focusing the window and without simulated keystrokes.',
+      approval: true,
+      schema: S(
+        {
+          on: { type: 'string', description: 'element id from mac_see / mac_element' },
+          value: { type: 'string' },
+          app: { type: 'string' },
+          window_id: { type: 'string' },
+        },
+        ['on', 'value'],
+      ),
+      required: ['on', 'value'],
+      handler: async (args) => {
+        const p = checkPeek(peek());
+        if (!p.ok) return p;
+        const flags = targetFlags(args);
+        const res = await runVariants(
+          p.bin,
+          [
+            ['set-value', String(args.value), '--on', String(args.on), ...flags],
+            ['set-value', String(args.value), '--on', String(args.on)],
+            ['set-value', '--on', String(args.on), String(args.value), ...flags],
+            ['set-value', '--on', String(args.on), '--value', String(args.value), ...flags],
+          ],
+          { timeout: 30 },
+        );
+        return finish(res, 'set-value');
+      },
+    },
+    {
+      name: 'mac_menu',
+      description: 'List the menu items of an application through the accessibility API. Read-only.',
+      approval: false,
+      schema: S({ app: { type: 'string' } }, []),
+      required: [],
+      handler: async (args) => {
+        const p = checkPeek(peek());
+        if (!p.ok) return p;
+        const flags = args.app ? ['--app', String(args.app)] : [];
+        const res = await runVariants(
+          p.bin,
+          [
+            ['menu', 'list', ...flags, '--json'],
+            ['menu', 'list', ...flags],
+          ],
+          { timeout: 30 },
+        );
+        const json = parseJson(res.stdout);
+        return {
+          ok: res.exit_code === 0,
+          menus: json ? (json.menus || json.data?.menus || json) : undefined,
+          output: json ? undefined : res.stdout.slice(0, 4000),
+          error: res.exit_code === 0 ? undefined : (res.stderr || '').trim().slice(0, 600),
+        };
+      },
+    },
+    {
+      name: 'mac_menu_click',
+      description:
+        'Trigger a menu item by name (e.g. "Save", "Copy Link") or a nested path ("File > Export") — no pointer, no coordinates.',
+      approval: true,
+      schema: S(
+        {
+          item: { type: 'string', description: 'name of the menu item' },
+          path: { type: 'string', description: 'nested path, e.g. "File > Export"' },
+          app: { type: 'string', description: 'required: the background menu click needs a target app' },
+        },
+        [],
+      ),
+      required: [],
+      handler: async (args) => {
+        const p = checkPeek(peek());
+        if (!p.ok) return p;
+        if (!args.item && !args.path) {
+          return { ok: false, error: 'missing_item', hint: 'Pass item ("Save") or path ("File > Export").' };
+        }
+        if (!args.app) {
+          return {
+            ok: false,
+            error: 'missing_app',
+            hint: 'A background menu click needs an explicit app: mac_menu_click {"app":"Safari","item":"Save"}.',
+          };
+        }
+        const flags = ['--app', String(args.app)];
+        const variants = args.path
+          ? [
+              ['menu', 'click', '--path', String(args.path), ...flags],
+              ['menu', 'click', String(args.path), ...flags],
+            ]
+          : [
+              ['menu', 'click', '--item', String(args.item), ...flags],
+              ['menu', 'click', String(args.item), ...flags],
+            ];
+        const res = await runVariants(p.bin, variants, { timeout: 30 });
+        return finish(res, 'menu-click');
+      },
+    },
+    {
+      name: 'mac_spaces',
+      description: 'List the macOS Spaces (virtual desktops) and which one is active. Read-only.',
+      approval: false,
+      schema: S({}, []),
+      required: [],
+      handler: async () => {
+        const p = checkPeek(peek());
+        if (!p.ok) return p;
+        const res = await runVariants(
+          p.bin,
+          [
+            ['space', 'list', '--json'],
+            ['space', 'list'],
+          ],
+          { timeout: 30 },
+        );
+        const json = parseJson(res.stdout);
+        return {
+          ok: res.exit_code === 0,
+          spaces: json ? (json.spaces || json.data?.spaces || json) : undefined,
+          output: json ? undefined : res.stdout.slice(0, 4000),
+          error: res.exit_code === 0 ? undefined : (res.stderr || '').trim().slice(0, 600),
+        };
+      },
+    },
+    {
+      name: 'mac_space_switch',
+      description:
+        'Move to another Space so the agent works on a separate virtual desktop and the user keeps the screen they are on.',
+      approval: true,
+      schema: S({ to: { type: 'string', description: 'space id or index from mac_spaces' } }, ['to']),
+      required: ['to'],
+      handler: async (args) => {
+        const p = checkPeek(peek());
+        if (!p.ok) return p;
+        const res = await runVariants(
+          p.bin,
+          [
+            ['space', 'switch', '--to', String(args.to), '--foreground'],
+            ['space', 'switch', String(args.to), '--foreground'],
+          ],
+          { timeout: 30 },
+        );
+        return finish(res, 'space-switch');
+      },
+    },
+    {
+      name: 'mac_wait',
+      description:
+        'Wait until an element with the given name/role appears (or disappears) and report what was seen. Read-only.',
+      approval: false,
+      schema: S(
+        {
+          name: { type: 'string' },
+          role: { type: 'string' },
+          value: { type: 'string' },
+          disappear: { type: 'boolean', description: 'wait until the element is gone' },
+          timeout: { type: 'number', description: 'seconds, default 20, max 120' },
+          app: { type: 'string' },
+        },
+        [],
+      ),
+      required: [],
+      handler: async (args) => {
+        const p = checkPeek(peek());
+        if (!p.ok) return p;
+        const limit = Math.min(120, Math.max(1, Number(args.timeout) || 20));
+        const deadline = Date.now() + limit * 1000;
+        let scanned = 0;
+        while (Date.now() < deadline) {
+          const seen = await searchSee(args);
+          scanned = seen.elements.length;
+          const hit = seen.elements.find((e) => matchElement(e, args));
+          if (args.disappear) {
+            if (!hit) return { ok: true, gone: true, found: false, scanned };
+          } else if (hit) {
+            return { ok: true, found: true, element: hit, scanned };
+          }
+          await new Promise((r) => setTimeout(r, 2000));
+        }
+        return {
+          ok: false,
+          found: false,
+          error: 'not_found',
+          reason: `no matching element within ${limit}s`,
+          scanned,
+        };
+      },
+    },
     {
       name: 'mac_permissions',
       description:

package/src/mcp.mjs

@@ -48,7 +48,7 @@ export async function handleMcp(req, res, ctx) {
           mcpResponse(id, {
             protocolVersion: PROTOCOL_VERSION,
             capabilities: { tools: { listChanged: false } },
-            serverInfo: { name: 'arena-bridge', version: '0.6.2' },
+            serverInfo: { name: 'arena-bridge', version: '0.6.4' },
             instructions:
               'Tools operate the user\'s own machine. Dangerous operations may return ' +
               'PROTECTED and require a local human approval.',

package/src/prompt.mjs

@@ -59,6 +59,11 @@ ${tools.join('\n')}
 | click a native app | \`mac_click\` with the element id from \`mac_see\`, a visible text, or \`{"x":..,"y":..}\` |
 | type into a native app | \`mac_type\`, then \`mac_key\` for Enter/Tab/cmd+s |
 | list or open applications | \`mac_apps\`, \`mac_app_launch\`, \`mac_app_focus\` |
+| find a control by its name, without a screenshot | \`mac_element\` (accessibility API: name, role, value) |
+| fill a field without typing and without focus | \`mac_set\` (sets the value through the accessibility API) |
+| use the application menu | \`mac_menu\` to list, \`mac_menu_click\` to trigger an item by name |
+| wait for a control to appear or vanish | \`mac_wait\` |
+| work on a separate virtual desktop | \`mac_spaces\`, \`mac_space_switch\` |
 | look at files | \`list_dir\` (top level only; add \`{"recursive":true}\` to go deeper), \`read_file\`, \`search_files\` |
 
 ## Browser control (Chrome over CDP)
@@ -75,6 +80,8 @@ ${tools.join('\n')}
 6. A visible window can be kept small and out of the way: \`chrome_launch {"headless":false,"width":900,"height":700,"x":-920,"y":40}\`.
 
 ## Desktop control (macOS, through Peekaboo)
+0. Prefer the accessibility API over pixels: controls are recognised by name and role, not by guessing
+   coordinates. \`mac_element\` finds them, \`mac_see\` returns the same elements with ids plus a screenshot.
 1. \`mac_see\` is the entry point: it takes a screenshot of the screen (or of one app window with
    \`{"app": "Safari", "mode": "window"}\`) and returns the clickable elements with their ids.
 2. Then \`mac_click\` (by id, by visible text or by coordinates) → \`mac_type\` → \`mac_key\` → \`mac_scroll\`.
@@ -84,6 +91,11 @@ ${tools.join('\n')}
 5. Screenshots are saved as PNG inside the authorized roots; read them back with \`file_get\`.
 6. Stay out of the user's way: do not pass \`foreground\`, do not focus windows and do not move the
    pointer unless the user asks for it. Background actions are delivered to the target window only.
+7. \`mac_set\` writes a value straight into a control (no keystrokes, no focus change);
+   \`mac_menu_click\` triggers a menu item by its name (it needs the \`app\` name) — both are more reliable than typing.
+8. \`mac_wait\` waits for a control to appear or disappear instead of sleeping and guessing.
+9. \`mac_spaces\` lists the macOS virtual desktops; \`mac_space_switch\` moves the agent to another
+   Space so the user keeps the screen they are looking at.
 
 ## Approvals
 ${trustLine}