arena-bridge 0.6.7 → 0.6.9

package/CHANGELOG.md

@@ -4,6 +4,25 @@ 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.9
+
+### Fixed
+- Desktop control survives a Peekaboo update: when the Peekaboo Bridge host loses its macOS
+  permissions (Screen Recording / Accessibility), the bridge falls back to the local Peekaboo
+  runtime and keeps working. If nothing can capture, the tool now says so instead of quietly
+  returning an empty element list.
+
+## 0.6.8
+
+### Added
+- Detailed work log: every call is recorded with its arguments, outcome and duration, and the
+  evidence is kept next to the log — screenshots taken on the desktop, the accessibility trees
+  that were read, menu trees and the list of Spaces.
+  - `audit_log` / `audit_artifact` tools and `GET /audit`, `GET /audit/artifact` endpoints let the
+    agent look back at what it saw.
+  - `arena-bridge audit` lists the calls, `arena-bridge audit artifacts` lists the saved files,
+    `arena-bridge audit <id>` prints one entry, `arena-bridge audit prune` removes old artifacts.
+
 ## 0.6.7
 
 ### 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-115%20passed-brightgreen.svg?style=flat-square" alt="tests">
+  <img src="https://img.shields.io/badge/tests-124%20passed-brightgreen.svg?style=flat-square" alt="tests">
 </p>
 
 <p align="center">
@@ -95,6 +95,7 @@ arena-bridge setup --root ~/projects
 | Группа | Инструменты | Что это |
 | --- | --- | --- |
 | Файлы | `list_dir` `read_file` `write_file` `edit_file` `delete_path` `search_files` `file_get` `file_put` | работа с файлами в разрешённых папках |
+| Журнал | `audit_log` `audit_artifact` | что делалось, какие снимки и деревья Accessibility сохранены |
 | Шелл | `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 |
@@ -199,6 +200,25 @@ macOS отдаёт приложениям два разных слоя: карт
 
 ---
 
+## Журнал работы с артефактами
+
+Каждый вызов записывается: аргументы, результат, время выполнения. Рядом с журналом хранятся
+**доказательства** — снимки экрана, деревья Accessibility, деревья меню, список рабочих столов.
+
+```bash
+arena-bridge audit                 # последние вызовы
+arena-bridge audit artifacts       # сохранённые файлы (скриншоты, деревья)
+arena-bridge audit <id>            # одна запись целиком
+arena-bridge audit prune           # удалить старые артефакты (по умолчанию старше 14 дней)
+arena-bridge audit dir             # где всё это лежит
+```
+
+Агенту доступно то же самое: `audit_log` (вызовы) и `audit_artifact` (сам артефакт — PNG в base64
+или дерево Accessibility в JSON), а также `GET /audit` и `GET /audit/artifact?entry=<id>&file=<name>`.
+Полезно, чтобы оглянуться назад: что было на экране и что находилось в интерфейсе.
+
+---
+
 ## Доверенное окно: работать без подтверждений
 
 ```bash
@@ -309,6 +329,8 @@ GET  /health          liveness (без авторизации)
 GET  /tools           каталог инструментов с JSON-схемами
 GET  /prompt          этот промпт для агента
 GET  /approvals       ожидающие подтверждения
+GET  /audit           журнал работы с артефактами
+GET  /audit/artifact  сохранённый артефакт (entry=, file=)
 POST /call            {"tool":"bash","args":{...}}
 POST /exec            {"command":"...","cwd":"...","timeout_sec":120}
 GET|PUT|DELETE /files?path=/abs/path

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arena-bridge",
-  "version": "0.6.7",
+  "version": "0.6.9",
   "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/audit.mjs

@@ -1,20 +1,31 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { CONFIG_DIR, AUDIT_PATH } from './config.mjs';
+import { CONFIG_DIR } from './config.mjs';
+
+/** The config directory is resolved on every call so tests and relocations stay isolated. */
+function configDir() {
+  return process.env.ARENA_BRIDGE_HOME || CONFIG_DIR;
+}
+
+export function auditPath() {
+  return path.join(configDir(), 'audit.log');
+}
 
 export function audit(entry) {
   try {
-    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    const dir = configDir();
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
     const rec = { ts: new Date().toISOString(), ...entry };
-    fs.appendFileSync(AUDIT_PATH, JSON.stringify(rec) + '\n', { mode: 0o600 });
+    fs.appendFileSync(auditPath(), JSON.stringify(rec) + '\n', { mode: 0o600 });
   } catch {
     /* auditing must never break the request */
   }
 }
 
 export function tailAudit(n = 50) {
-  if (!fs.existsSync(AUDIT_PATH)) return [];
-  const lines = fs.readFileSync(AUDIT_PATH, 'utf8').trim().split('\n').filter(Boolean);
+  const file = auditPath();
+  if (!fs.existsSync(file)) return [];
+  const lines = fs.readFileSync(file, 'utf8').trim().split('\n').filter(Boolean);
   return lines
     .slice(-n)
     .map((l) => {
@@ -25,3 +36,76 @@ export function tailAudit(n = 50) {
       }
     });
 }
+
+/* ------------------------------------------------------------------ *
+ * artifacts: screenshots, accessibility trees and other evidence
+ * ------------------------------------------------------------------ */
+
+export function auditDir() {
+  return path.join(configDir(), 'audit');
+}
+
+export function saveArtifact(entryId, kind, name, data, meta = {}) {
+  try {
+    const dir = path.join(auditDir(), String(entryId));
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const file = path.join(dir, path.basename(String(name)));
+    fs.writeFileSync(file, data, { mode: 0o600 });
+    const bytes = Buffer.isBuffer(data) ? data.length : Buffer.byteLength(String(data));
+    return { kind, name: path.basename(String(name)), path: file, bytes, ...meta };
+  } catch {
+    return null;
+  }
+}
+
+export function readArtifact(entryId, name) {
+  try {
+    const file = path.join(auditDir(), String(entryId), path.basename(String(name)));
+    if (!fs.existsSync(file)) return null;
+    return { file, data: fs.readFileSync(file) };
+  } catch {
+    return null;
+  }
+}
+
+export function listArtifacts() {
+  const dir = auditDir();
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const entry of fs.readdirSync(dir)) {
+    const sub = path.join(dir, entry);
+    let files = [];
+    try {
+      files = fs
+        .readdirSync(sub)
+        .filter((f) => fs.statSync(path.join(sub, f)).isFile())
+        .map((f) => ({ name: f, bytes: fs.statSync(path.join(sub, f)).size }));
+    } catch {
+      /* ignore */
+    }
+    if (files.length) out.push({ entry, files });
+  }
+  return out;
+}
+
+export function pruneArtifacts(days = 14) {
+  const dir = auditDir();
+  if (!fs.existsSync(dir)) return { removed: 0, freed_bytes: 0 };
+  const cutoff = Date.now() - Number(days) * 86400000;
+  let removed = 0;
+  let freed = 0;
+  for (const entry of fs.readdirSync(dir)) {
+    const sub = path.join(dir, entry);
+    try {
+      const st = fs.statSync(sub);
+      if (st.mtimeMs < cutoff) {
+        freed += st.size;
+        fs.rmSync(sub, { recursive: true, force: true });
+        removed++;
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+  return { removed, freed_bytes: freed };
+}

package/src/browser.mjs

@@ -652,6 +652,9 @@ export class BrowserManager {
           }
           const { data } = await session.cdp.send('Page.captureScreenshot', params, tab.sessionId);
           const b64 = String(data || '');
+          if (ctx.artifact && b64) {
+            ctx.artifact('screenshot', 'page.png', Buffer.from(b64, 'base64'), { source: 'chrome_screenshot' });
+          }
           if (args.path) {
             const chk = checkPath(args.path, ctx.cfg, ctx.base, { write: true });
             if (!chk.ok) return { ok: false, error: chk.error, reason: chk.reason };

package/src/cli.mjs

@@ -9,7 +9,7 @@ import { createHubServer } from './hub.mjs';
 import { runDevice } from './device.mjs';
 import { buildPrompt } from './prompt.mjs';
 import { listApprovals, decide } from './approvals.mjs';
-import { tailAudit } from './audit.mjs';
+import { tailAudit, auditDir, listArtifacts, pruneArtifacts } from './audit.mjs';
 import { startTunnel, isPortOpen } from './tunnel.mjs';
 import { spawn, execSync } from 'node:child_process';
 import { parseDuration, trustState, saveTrust, clearTrust } from './trust.mjs';
@@ -377,10 +377,33 @@ function cmdTrust(args) {
 }
 
 function cmdAudit(args) {
+  const what = args._[1];
+  if (what === 'dir') {
+    console.log(auditDir());
+    return;
+  }
+  if (what === 'prune') {
+    const res = pruneArtifacts(Number(args.flags.days || 14));
+    console.log(`removed ${res.removed} artifact folder(s), ${res.freed_bytes} bytes`);
+    return;
+  }
+  if (what === 'artifacts') {
+    for (const item of listArtifacts()) {
+      const files = item.files.map((f) => `${f.name} (${f.bytes} B)`).join(', ');
+      console.log(`${item.entry}  ${files}`);
+    }
+    return;
+  }
+  if (what && what.length > 6) {
+    const rec = tailAudit(500).find((e) => e.id === what);
+    console.log(rec ? JSON.stringify(rec, null, 2) : `no entry with id ${what}`);
+    return;
+  }
   const n = Number(args.flags.n || 30);
   for (const rec of tailAudit(n)) {
+    const arts = (rec.artifacts || []).map((a) => a.name).join(' ');
     console.log(
-      `${rec.ts} ${String(rec.tool).padEnd(18)} ${String(rec.status).padEnd(16)} ${rec.duration_ms ?? ''}${
+      `${rec.ts} ${String(rec.tool).padEnd(18)} ${String(rec.status).padEnd(14)} ${String(rec.duration_ms ?? '').padStart(6)}ms${arts ? '  ' + arts : ''}${
         rec.error ? ' ' + rec.error : ''
       }`,
     );

package/src/direct.mjs

@@ -6,6 +6,7 @@ import { buildPrompt } from './prompt.mjs';
 import { listApprovals, decide } from './approvals.mjs';
 import { checkPath } from './policy.mjs';
 import { loadConfig } from './config.mjs';
+import { tailAudit, readArtifact, auditDir } from './audit.mjs';
 
 export function createDirectServer(cfg, engine) {
   const mcpCtx = {
@@ -29,7 +30,7 @@ export function createDirectServer(cfg, engine) {
           ok: true,
           mode: 'direct',
           device: cfg.device,
-          version: '0.6.7',
+          version: '0.6.9',
           uptime_sec: Math.round(process.uptime()),
         });
       }
@@ -62,6 +63,29 @@ export function createDirectServer(cfg, engine) {
         });
       }
 
+      if (req.method === 'GET' && p === '/audit') {
+        const limit = Math.min(200, Number(url.searchParams.get('limit')) || 30);
+        return sendJson(res, 200, { ok: true, entries: tailAudit(limit), artifacts_dir: auditDir() });
+      }
+
+      if (req.method === 'GET' && p === '/audit/artifact') {
+        const entry = url.searchParams.get('entry');
+        const file = url.searchParams.get('file');
+        if (!entry || !file) {
+          return sendJson(res, 400, { ok: false, error: 'entry and file query parameters are required' });
+        }
+        const art = readArtifact(entry, file);
+        if (!art) return sendJson(res, 404, { ok: false, error: 'artifact_not_found' });
+        const type = /\.png$/i.test(art.file)
+          ? 'image/png'
+          : /\.jpe?g$/i.test(art.file)
+            ? 'image/jpeg'
+            : /\.json$/i.test(art.file)
+              ? 'application/json; charset=utf-8'
+              : 'text/plain; charset=utf-8';
+        return sendRaw(res, 200, art.data, type);
+      }
+
       if (req.method === 'GET' && p === '/approvals') {
         return sendJson(res, 200, { ok: true, approvals: listApprovals() });
       }

package/src/engine.mjs

@@ -4,7 +4,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { checkPath, resolveTarget, isInside } from './policy.mjs';
-import { audit } from './audit.mjs';
+import { audit, saveArtifact, tailAudit, readArtifact, auditDir } from './audit.mjs';
 import { requestApproval } from './approvals.mjs';
 import { loadConfig, CONFIG_PATH } from './config.mjs';
 import { BrowserManager } from './browser.mjs';
@@ -393,6 +393,63 @@ export function toolCatalog() {
         return { ok: true, path: chk.abs, bytes: data.length };
       },
     },
+    {
+      name: 'audit_log',
+      description:
+        'Read the detailed log of what happened on this machine: every tool call with its arguments, outcome and saved artifacts (screenshots, accessibility trees). Read-only.',
+      approval: false,
+      schema: S(
+        {
+          limit: { type: 'number', description: 'how many entries to return, default 30' },
+          tool: { type: 'string', description: 'only entries of this tool' },
+          since: { type: 'string', description: 'only entries newer than this ISO timestamp' },
+        },
+        [],
+      ),
+      required: [],
+      handler: async (args) => {
+        const n = Math.min(200, Number(args.limit) || 30);
+        let entries = tailAudit(n * 4);
+        if (args.tool) entries = entries.filter((e) => e.tool === args.tool);
+        if (args.since) {
+          const since = Date.parse(String(args.since));
+          if (!Number.isNaN(since)) entries = entries.filter((e) => Date.parse(e.ts) >= since);
+        }
+        entries = entries.slice(-n);
+        return { ok: true, count: entries.length, entries, artifacts_dir: auditDir() };
+      },
+    },
+    {
+      name: 'audit_artifact',
+      description:
+        'Fetch a saved artifact of a logged call: a screenshot (PNG as base64) or an accessibility tree (JSON). Read-only.',
+      approval: false,
+      schema: S(
+        {
+          entry: { type: 'string', description: 'entry id from audit_log' },
+          file: { type: 'string', description: 'artifact file name, e.g. "screen.png" or "ax-tree.json"' },
+        },
+        ['entry', 'file'],
+      ),
+      required: ['entry', 'file'],
+      handler: async (args) => {
+        const art = readArtifact(args.entry, args.file);
+        if (!art) {
+          return { ok: false, error: 'artifact_not_found', hint: 'Run audit_log to see the available artifacts.' };
+        }
+        if (/\.(png|jpe?g)$/i.test(art.file)) {
+          return { ok: true, kind: 'image', file: art.file, bytes: art.data.length, image_base64: art.data.toString('base64') };
+        }
+        const text = art.data.toString('utf8');
+        let json = null;
+        try {
+          json = JSON.parse(text);
+        } catch {
+          /* not json */
+        }
+        return { ok: true, kind: json ? 'json' : 'text', file: art.file, bytes: art.data.length, content: json ?? text.slice(0, 200000) };
+      },
+    },
     {
       name: 'sysinfo',
       description: 'Read-only information about the remote machine: OS, user, uptime, memory, disks, network interfaces.',
@@ -581,6 +638,17 @@ export class Engine {
     if (!tool) return { ok: false, error: `unknown tool: ${name}` };
     const started = Date.now();
     let approval = null;
+    const entryId = `${new Date().toISOString().replace(/[:.]/g, '-')}-${String(name).replace(/[^\w.-]/g, '_')}-${Math.random()
+      .toString(36)
+      .slice(2, 8)}`;
+    const ctx = Object.create(this);
+    ctx.entryId = entryId;
+    ctx.artifacts = [];
+    ctx.artifact = (kind, file, data, meta) => {
+      const saved = saveArtifact(entryId, kind, file, data, meta);
+      if (saved) ctx.artifacts.push(saved);
+      return saved;
+    };
 
     // pick up policy changes (roots, protected, requireApproval) without a restart
     try {
@@ -598,16 +666,16 @@ export class Engine {
       const trust = trustState();
       if (trustAllows(trust, tool.name, args, this.cfg)) {
         if (this.cfg.audit !== false) {
-          audit({ tool: tool.name, args, status: 'ok', via: 'trust_window' });
+          audit({ id: entryId, tool: tool.name, args, status: 'ok', via: 'trust_window' });
         }
-        const res = await tool.handler(args, this);
+        const res = await tool.handler(args, ctx);
         return res;
       }
       approval = await requestApproval(tool.name, args, this.cfg);
       if (!approval.approved) {
         const status = approval.rec?.status || 'denied';
         if (this.cfg.audit !== false) {
-          audit({ tool: tool.name, args, status: 'approval_denied', approval_status: status });
+          audit({ id: entryId, tool: tool.name, args, status: 'approval_denied', approval_status: status });
         }
         const pending = status === 'pending' || status === 'timeout' || status === 'expired';
         return {
@@ -627,21 +695,31 @@ export class Engine {
     }
 
     try {
-      const res = await tool.handler(args, this);
+      const res = await tool.handler(args, ctx);
       if (this.cfg.audit !== false) {
         audit({
+          id: entryId,
           tool: tool.name,
           args,
           status: res.ok ? 'ok' : 'error',
           duration_ms: Date.now() - started,
           exit_code: res.exit_code,
           error: res.ok ? undefined : res.error,
+          artifacts: ctx.artifacts.length ? ctx.artifacts : undefined,
         });
       }
       return res;
     } catch (e) {
       if (this.cfg.audit !== false) {
-        audit({ tool: tool.name, args, status: 'exception', duration_ms: Date.now() - started, error: e.message });
+        audit({
+          id: entryId,
+          tool: tool.name,
+          args,
+          status: 'exception',
+          duration_ms: Date.now() - started,
+          error: e.message,
+          artifacts: ctx.artifacts.length ? ctx.artifacts : undefined,
+        });
       }
       return { ok: false, error: e.message };
     }

package/src/hub.mjs

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

package/src/mac.mjs

@@ -193,6 +193,7 @@ export function macTools(cfg = {}) {
         ['see', '--tree', '--no-screenshot', '--json', ...targetFlags(args)],
         ['see', '--tree', '--no-screenshot', '--no-remote', '--json', ...targetFlags(args)],
         ['see', '--tree', '--json', ...targetFlags(args)],
+        ['see', '--no-remote', '--tree', '--json', ...targetFlags(args)],
         ['see', '--json', ...targetFlags(args)],
       ];
     }
@@ -213,7 +214,8 @@ export function macTools(cfg = {}) {
       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;
+      const denied = isPermissionError(json, res);
+      if (res.exit_code !== 0 && !denied && !UNKNOWN.test(res.stderr || '')) break;
     }
     return best;
   };
@@ -259,6 +261,15 @@ export function macTools(cfg = {}) {
         if (!outPath.ok) return { ok: false, error: outPath.error, reason: outPath.reason };
         ensureDir(path.dirname(outPath.abs));
         const seen = await collectSee(args, outPath.abs);
+        const failure = peekError(seen.json);
+        if (failure && !seen.elements.length) {
+          return {
+            ok: false,
+            error: 'peekaboo_failed',
+            reason: failure.message || String(failure.code || 'peekaboo returned an error'),
+            hint: PERMISSION_HINT,
+          };
+        }
         const elements = seen.elements.slice(0, 300);
         const saved = fs.existsSync(outPath.abs);
         if (!saved) {
@@ -284,6 +295,21 @@ export function macTools(cfg = {}) {
           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;
+        if (ctx.artifact) {
+          try {
+            if (fs.existsSync(outPath.abs)) {
+              ctx.artifact('screenshot', 'screen.png', fs.readFileSync(outPath.abs), { source: 'mac_see' });
+            }
+            if (seen.json) {
+              ctx.artifact('ax-tree', 'ax-tree.json', JSON.stringify(seen.json, null, 2), {
+                source: 'mac_see',
+                elements: seen.elements.length,
+              });
+            }
+          } catch {
+            /* artifacts are best effort */
+          }
+        }
         return out;
       },
     },
@@ -593,11 +619,18 @@ export function macTools(cfg = {}) {
         [],
       ),
       required: [],
-      handler: async (args) => {
+      handler: async (args, ctx) => {
         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);
+        if (ctx.artifact && seen.json) {
+          ctx.artifact('ax-tree', 'ax-tree.json', JSON.stringify(seen.json, null, 2), {
+            source: 'mac_element',
+            elements: seen.elements.length,
+            query: args.name || args.role || null,
+          });
+        }
         return {
           ok: true,
           matches,
@@ -645,7 +678,7 @@ export function macTools(cfg = {}) {
       approval: false,
       schema: S({ app: { type: 'string' } }, []),
       required: [],
-      handler: async (args) => {
+      handler: async (args, ctx) => {
         const p = checkPeek(peek());
         if (!p.ok) return p;
         const flags = menuFlags(args);
@@ -659,6 +692,9 @@ export function macTools(cfg = {}) {
           { timeout: 30 },
         );
         const json = parseJson(res.stdout);
+        if (ctx.artifact && json) {
+          ctx.artifact('menu-tree', 'menu-tree.json', JSON.stringify(json, null, 2), { source: 'mac_menu' });
+        }
         return {
           ok: res.exit_code === 0,
           menus: json ? (json.menus || json.data?.menus || json.data?.menu_structure || json) : undefined,
@@ -716,7 +752,7 @@ export function macTools(cfg = {}) {
       approval: false,
       schema: S({}, []),
       required: [],
-      handler: async () => {
+      handler: async (args, ctx) => {
         const p = checkPeek(peek());
         if (!p.ok) return p;
         const res = await runVariants(
@@ -729,6 +765,9 @@ export function macTools(cfg = {}) {
           { timeout: 30 },
         );
         const json = parseJson(res.stdout);
+        if (ctx.artifact && json) {
+          ctx.artifact('spaces', 'spaces.json', JSON.stringify(json, null, 2), { source: 'mac_spaces' });
+        }
         return {
           ok: res.exit_code === 0,
           spaces: json ? (json.spaces || json.data?.spaces || json) : undefined,
@@ -744,7 +783,7 @@ export function macTools(cfg = {}) {
       approval: true,
       schema: S({ to: { type: 'string', description: 'space id or index from mac_spaces' } }, ['to']),
       required: ['to'],
-      handler: async (args) => {
+      handler: async (args, ctx) => {
         const p = checkPeek(peek());
         if (!p.ok) return p;
         const res = await runVariants(
@@ -775,14 +814,16 @@ export function macTools(cfg = {}) {
         [],
       ),
       required: [],
-      handler: async (args) => {
+      handler: async (args, ctx) => {
         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;
+        let last = null;
         while (Date.now() < deadline) {
           const seen = await searchSee(args);
+          last = seen;
           scanned = seen.elements.length;
           const hit = seen.elements.find((e) => matchElement(e, args));
           if (args.disappear) {
@@ -792,6 +833,12 @@ export function macTools(cfg = {}) {
           }
           await new Promise((r) => setTimeout(r, 2000));
         }
+        if (ctx.artifact && last?.json) {
+          ctx.artifact('ax-tree', 'ax-tree.json', JSON.stringify(last.json, null, 2), {
+            source: 'mac_wait',
+            elements: scanned,
+          });
+        }
         return {
           ok: false,
           found: false,
@@ -808,7 +855,7 @@ export function macTools(cfg = {}) {
       approval: false,
       schema: S({}, []),
       required: [],
-      handler: async () => {
+      handler: async (args, ctx) => {
         const p = checkPeek(peek());
         if (!p.ok) {
           return {
@@ -831,6 +878,25 @@ export function macTools(cfg = {}) {
   ];
 }
 
+/** The Peekaboo envelope reports a host that lost its macOS permissions. */
+function peekError(json) {
+  if (!json || typeof json !== 'object') return null;
+  const err = json.error;
+  if (err && typeof err === 'object' && (err.code || err.message)) return err;
+  return null;
+}
+
+function isPermissionError(json, res) {
+  const err = peekError(json);
+  const text = `${err?.code || ''} ${err?.message || ''} ${res?.stderr || ''}`;
+  return /permission|screen recording|accessibility|event synthesizing/i.test(text);
+}
+
+const PERMISSION_HINT =
+  'The Peekaboo host that captures the screen lost its macOS permissions (this happens after a Peekaboo update). ' +
+  'Re-grant Screen Recording and Accessibility to "Peekaboo Bridge" in System Settings → Privacy & Security, ' +
+  'or let the bridge use the local runtime (--no-remote). Run mac_permissions for the current state.';
+
 function menuFlags(args) {
   const f = [];
   if (args.app) f.push('--app', String(args.app));

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.7' },
+            serverInfo: { name: 'arena-bridge', version: '0.6.9' },
             instructions:
               'Tools operate the user\'s own machine. Dangerous operations may return ' +
               'PROTECTED and require a local human approval.',

package/src/prompt.mjs

@@ -97,6 +97,13 @@ ${tools.join('\n')}
 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.
 
+## Work log with evidence
+Every call is logged with its arguments, result and duration. Screenshots taken on the desktop and
+the accessibility trees that were read are stored next to the log.
+- \`audit_log\` — the recent calls (filter by tool or time).
+- \`audit_artifact\` — fetch a saved artifact: a screenshot (base64 PNG) or an accessibility tree (JSON).
+Use them when you need to look back at what was on the screen or what the interface contained.
+
 ## Approvals
 ${trustLine}
 - When a call answers \`APPROVAL_PENDING\` it carries an \`approval_id\`: tell the user to run