arena-bridge 0.7.17 → 0.7.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,23 @@ All notable changes to this project are documented here.
4
4
  The format follows [Keep a Changelog](https://keepachangelog.com/) and the project uses
5
5
  [Semantic Versioning](https://semver.org/).
6
6
 
7
+ ## 0.7.19
8
+
9
+ ### Fixed
10
+ - Approval requests now become `timeout` or `expired` records on disk and cannot be accepted after they are no longer actionable.
11
+ - Stale pending requests expire when listed or decided; failed late approvals cannot open a trust window.
12
+ - Agent recovery hints explain that timed-out requests are closed and require a fresh call or trust window.
13
+ - An explicit Peekaboo path is authoritative rather than silently falling back to another installation.
14
+
15
+ ## 0.7.18
16
+
17
+ ### Fixed
18
+ - Service reinstall is queued as an independent one-shot launchd job, so stopping the bridge does not kill its own installer. Submission errors are reported, and reload outcome is recorded separately.
19
+ - Native helper forwards SIGINT as SIGINT and SIGTERM as SIGTERM; signal handling and child exit status verified on macOS.
20
+
21
+ ### Documentation
22
+ - Clarified permission names, update caveats and screen-capture verification; recorded service lifecycle follow-up plan.
23
+
7
24
  ## 0.7.17
8
25
 
9
26
  ### Fixed
package/README.md CHANGED
@@ -319,16 +319,37 @@ Apple Silicon. Готовые сборки для обеих архитекту
319
319
 
320
320
  ### Разрешения macOS
321
321
 
322
- Мосту нужны два разрешения: «Запись экрана» (снимки) и «Управление доступностью» (дерево
323
- элементов). macOS записывает разрешение на того, кто запросил его сверху, поэтому служба моста
324
- стартует через маленький помощник внутри подписанного бандла приложения
325
- (`Arena Bridge.app/Contents/Helpers/arena-bridge-agent`). В списке «Запись экрана» такая строка
326
- называется как приложение — «Arena Bridge», а не `node`.
327
-
328
- Строку `node`, если она осталась от прежней установки, можно удалить кнопкой «−»: новая запись
329
- придёт под именем приложения, и её нужно один раз включить в настройках. Служба моста запускается
330
- из постоянных папок (`~/.local/share/fnm/node-versions/...`), а не из временной папки версии
331
- менеджера, поэтому разрешение само по себе не слетает.
322
+ Мосту нужны два разрешения в «Конфиденциальность и безопасность»:
323
+
324
+ - **Запись экрана и системного аудио** → включите **Arena Bridge**.
325
+ - **Универсальный доступ (Accessibility)** → включите **arena-bridge-agent**.
326
+
327
+ Это части одного приложения. После изменения разрешений может потребоваться перезапуск службы.
328
+ Старую запись `node` удаляйте только после проверки снимков и дерева элементов (`mac_see`).
329
+ Успешное сохранение PNG ещё не доказывает доступ: на снимке должно быть содержимое окон,
330
+ а не только обои. Без Accessibility снимок может работать, но дерево элементов будет пустым.
331
+
332
+ После установки приложения переустановите службу (`arena-bridge service install` с прежними
333
+ параметрами туннеля), чтобы она использовала помощник внутри бандла
334
+ (`Contents/Helpers/arena-bridge-agent`). Без приложения CLI продолжает работать, но названия
335
+ записей разрешений могут отличаться.
336
+
337
+ Стабильный путь к интерпретатору снижает риск потери разрешений, но не гарантирует их сохранение
338
+ после изменения подписи, пути или обновления приложения. Проверяйте разрешения для реально
339
+ запущенной установки. В частности, обновление ad-hoc-подписанного помощника может оставить
340
+ переключатели включёнными, но фактически лишить процесс доступа: выключите и снова включите
341
+ **Arena Bridge** в записи экрана и **arena-bridge-agent** в Accessibility, затем перезапустите службу.
342
+ Если это не помогло, удалите только эти две записи кнопкой «−» и добавьте заново через «+»:
343
+ `/Applications/Arena Bridge.app` и
344
+ `/Applications/Arena Bridge.app/Contents/Helpers/arena-bridge-agent` соответственно.
345
+ Не храните резервные сборки с тем же bundle id как зарегистрированные `.app`:
346
+ это затрудняет выбор нужной установки.
347
+
348
+ Переустановка службы выполняется отдельным одноразовым системным заданием через несколько
349
+ секунд после команды. Это позволяет переустанавливать мост через сам мост. `scheduled` означает
350
+ только постановку задания, не успешный запуск. Результат загрузки службы — в
351
+ `~/.arena-bridge/service-reload.status`, ошибки — в `~/.arena-bridge/logs/service-reload.err.log`.
352
+ Проверяйте также `arena-bridge service status` и `/health`: `loaded` ещё не гарантирует работу туннеля.
332
353
 
333
354
  ### Как переименовать
334
355
 
@@ -431,8 +452,10 @@ arena-bridge browser close work # закрыть окно этого пр
431
452
  * **Пути ограничены**: всё вне `roots` — `PROTECTED`. Защищённый список по умолчанию включает
432
453
  `~/.ssh`, `~/.aws`, `~/.arena-bridge`, `~/.npmrc`, профили браузеров, ключи.
433
454
  * **Подтверждения**: `bash`, запись, удаление, управление вашим Chrome и десктопом ждут
434
- `arena-bridge approve <id>`. Ответ `APPROVAL_PENDING` содержит `approval_id` — покажите его
435
- пользователю и повторите вызов один раз.
455
+ `arena-bridge approve <id>`. Подтверждать нужно, пока вызов ожидает решения.
456
+ После `timeout` или `expired` запрос закрыт и его `approval_id` больше не принимается.
457
+ Для продолжения откройте `arena-bridge trust --for 1h` и повторите вызов один раз либо
458
+ согласуйте новый вызов, который пользователь подтвердит во время ожидания.
436
459
  * **Журнал**: `~/.arena-bridge/audit.log` (JSONL) — кто, что и когда вызвал.
437
460
  * **Транспорт**: сервер слушает `127.0.0.1`, наружу — только туннель с HTTPS.
438
461
 
@@ -527,7 +550,7 @@ arena_bridge/ тот же функционал на Python (stdlib only)
527
550
  | `port 8787 is already in use` | остановите старый экземпляр (`Ctrl+C`) или `arena-bridge start --port 8788` |
528
551
  | туннель не поднимается | `cloudflared` по умолчанию использует QUIC и может быть заблокирован — `arena-bridge tunnel --protocol http2` (это поведение по умолчанию) |
529
552
  | агент не видит файлы | проверьте `arena-bridge doctor` и `roots` в `~/.arena-bridge/config.json`; вне `roots` всё равно `PROTECTED` |
530
- | `APPROVAL_PENDING` | покажите пользователю `arena-bridge approve <id>` или откройте `arena-bridge trust --for 1h` |
553
+ | `APPROVAL_PENDING` | при `timeout`/`expired` старый запрос закрыт: согласуйте новый вызов или попросите открыть `arena-bridge trust --for 1h` |
531
554
  | скриншоты не работают | `mac_permissions` — выдайте терминалу Screen Recording и Accessibility |
532
555
  | `peekaboo_not_found` | поставьте Peekaboo или укажите путь: `arena-bridge init` + `peekabooPath` в конфиге |
533
556
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "arena-bridge",
3
- "version": "0.7.17",
3
+ "version": "0.7.19",
4
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.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -19,9 +19,9 @@
19
19
  "node": ">=18"
20
20
  },
21
21
  "scripts": {
22
- "test": "node test/smoke.mjs && node test/browser.test.mjs && node test/mac.test.mjs",
23
- "test:node": "node test/smoke.mjs && node test/browser.test.mjs && node test/mac.test.mjs",
24
- "test:python": "python3 test/test_bridge.py && python3 test/test_browser.py && python3 test/test_mac.py",
22
+ "test": "node --test test/approvals.test.mjs && node test/smoke.mjs && node test/browser.test.mjs && node test/mac.test.mjs && node test/service.test.mjs",
23
+ "test:node": "node --test test/approvals.test.mjs && node test/smoke.mjs && node test/browser.test.mjs && node test/mac.test.mjs && node test/service.test.mjs",
24
+ "test:python": "python3 test/test_approvals.py && python3 test/test_bridge.py && python3 test/test_browser.py && python3 test/test_mac.py && python3 test/test_service.py",
25
25
  "pack:check": "npm pack --dry-run"
26
26
  },
27
27
  "repository": {
package/src/approvals.mjs CHANGED
@@ -11,6 +11,16 @@ function fileOf(id) {
11
11
  return path.join(APPROVALS_DIR, `${id}.json`);
12
12
  }
13
13
 
14
+ function expireIfNeeded(file, rec, now = Date.now()) {
15
+ if (rec.status === 'pending' && rec.expiresAt && now >= rec.expiresAt) {
16
+ rec.status = 'expired';
17
+ rec.decidedAt = now;
18
+ rec.decidedBy = 'system';
19
+ fs.writeFileSync(file, JSON.stringify(rec, null, 2), { mode: 0o600 });
20
+ }
21
+ return rec;
22
+ }
23
+
14
24
  export function listApprovals() {
15
25
  if (!fs.existsSync(APPROVALS_DIR)) return [];
16
26
  return fs
@@ -18,7 +28,8 @@ export function listApprovals() {
18
28
  .filter((f) => f.endsWith('.json'))
19
29
  .map((f) => {
20
30
  try {
21
- return JSON.parse(fs.readFileSync(path.join(APPROVALS_DIR, f), 'utf8'));
31
+ const file = path.join(APPROVALS_DIR, f);
32
+ return expireIfNeeded(file, JSON.parse(fs.readFileSync(file, 'utf8')));
22
33
  } catch {
23
34
  return null;
24
35
  }
@@ -36,6 +47,7 @@ export function decide(id, decision, by = 'cli') {
36
47
  } catch (e) {
37
48
  return { ok: false, error: e.message };
38
49
  }
50
+ rec = expireIfNeeded(file, rec);
39
51
  if (rec.status !== 'pending') return { ok: false, error: `already ${rec.status}` };
40
52
  rec.status = decision === 'approve' ? 'approved' : 'denied';
41
53
  rec.decidedAt = Date.now();
@@ -117,10 +129,17 @@ export async function requestApproval(tool, args, cfg) {
117
129
  continue;
118
130
  }
119
131
  if (cur.status === 'approved') return { approved: true, rec: cur };
120
- if (cur.status === 'denied') return { approved: false, rec: cur };
121
- if (cur.expiresAt && Date.now() > cur.expiresAt) {
122
- return { approved: false, rec: { ...cur, status: 'expired' } };
132
+ if (cur.status !== 'pending') return { approved: false, rec: cur };
133
+ if (cur.expiresAt && Date.now() >= cur.expiresAt) {
134
+ return { approved: false, rec: expireIfNeeded(fileOf(id), cur) };
123
135
  }
124
136
  }
125
- return { approved: false, rec: { ...rec, status: 'timeout' } };
137
+ const timedOut = expireIfNeeded(fileOf(id), JSON.parse(fs.readFileSync(fileOf(id), 'utf8')));
138
+ if (timedOut.status === 'pending') {
139
+ timedOut.status = 'timeout';
140
+ timedOut.decidedAt = Date.now();
141
+ timedOut.decidedBy = 'system';
142
+ fs.writeFileSync(fileOf(id), JSON.stringify(timedOut, null, 2), { mode: 0o600 });
143
+ }
144
+ return { approved: timedOut.status === 'approved', rec: timedOut };
126
145
  }
package/src/cli.mjs CHANGED
@@ -495,7 +495,9 @@ function cmdService(args) {
495
495
  authtoken: args.flags.authtoken,
496
496
  port: args.flags.port,
497
497
  });
498
+ if (!res.ok) throw new Error(res.detail);
498
499
  console.log(`\u2713 service installed: ${res.plist}`);
500
+ console.log(' reload scheduled in 3 seconds; check: arena-bridge service status');
499
501
  console.log(' the bridge now starts with the system and keeps a public URL alive');
500
502
  console.log(' current URL: arena-bridge url');
501
503
  return;
package/src/direct.mjs CHANGED
@@ -73,7 +73,7 @@ export function createDirectServer(cfg, engine) {
73
73
  ok: true,
74
74
  mode: 'direct',
75
75
  device: cfg.device,
76
- version: '0.7.17',
76
+ version: '0.7.19',
77
77
  uptime_sec: Math.round(process.uptime()),
78
78
  });
79
79
  }
package/src/engine.mjs CHANGED
@@ -685,11 +685,11 @@ export class Engine {
685
685
  status,
686
686
  pending,
687
687
  reason: pending
688
- ? `waiting for a local human decision on tool "${tool.name}"`
688
+ ? `approval wait ended (${status}) for tool "${tool.name}"; this request is closed`
689
689
  : `human ${status} tool "${tool.name}"`,
690
690
  approval_id: approval.rec?.id || null,
691
691
  hint: pending
692
- ? 'Tell the user to run: arena-bridge approve <approval_id> - or open a trust window for hands-free work: arena-bridge trust --for 1h. Then retry the call once.'
692
+ ? 'This approval_id is closed and cannot be approved. Ask the user to open a trust window: arena-bridge trust --for 1h. Then retry the call once, or arrange a fresh call for approval while it is waiting.'
693
693
  : 'The user declined this action. Do not retry it; ask what to do instead.',
694
694
  };
695
695
  }
package/src/hub.mjs CHANGED
@@ -90,7 +90,7 @@ export function createHubServer(cfg) {
90
90
  return sendJson(res, 200, {
91
91
  ok: true,
92
92
  mode: 'hub',
93
- version: '0.7.17',
93
+ version: '0.7.19',
94
94
  devices: [...devices.keys()],
95
95
  });
96
96
  }
package/src/mac.mjs CHANGED
@@ -18,8 +18,9 @@ const NOT_FOUND_HINT =
18
18
  'peekaboo is not installed on this machine. Install it (macOS: brew install peekaboo, or download the release from https://github.com/openclaw/Peekaboo) and make sure the binary is on PATH.';
19
19
 
20
20
  export function findPeekaboo(cfg = {}) {
21
- const explicit = cfg.peekabooPath || process.env.PEEKABOO_PATH;
22
- if (explicit && fs.existsSync(explicit)) return explicit;
21
+ if (cfg.peekabooPath) return fs.existsSync(cfg.peekabooPath) ? cfg.peekabooPath : null;
22
+ const explicit = process.env.PEEKABOO_PATH;
23
+ if (explicit) return fs.existsSync(explicit) ? explicit : null;
23
24
  for (const c of PEEKABOO_CANDIDATES) if (fs.existsSync(c)) return c;
24
25
  for (const d of (process.env.PATH || '').split(path.delimiter)) {
25
26
  if (!d) continue;
package/src/mcp.mjs CHANGED
@@ -48,7 +48,7 @@ export async function handleMcp(req, res, ctx) {
48
48
  mcpResponse(id, {
49
49
  protocolVersion: PROTOCOL_VERSION,
50
50
  capabilities: { tools: { listChanged: false } },
51
- serverInfo: { name: 'arena-bridge', version: '0.7.17' },
51
+ serverInfo: { name: 'arena-bridge', version: '0.7.19' },
52
52
  instructions:
53
53
  'Tools operate the user\'s own machine. Dangerous operations may return ' +
54
54
  'PROTECTED and require a local human approval.',
package/src/prompt.mjs CHANGED
@@ -116,9 +116,10 @@ Use it when a step takes long or when you need a decision: one message is enough
116
116
 
117
117
  ## Approvals
118
118
  ${trustLine}
119
- - When a call answers \`APPROVAL_PENDING\` it carries an \`approval_id\`: tell the user to run
120
- \`arena-bridge approve <approval_id>\` on their machine (or \`arena-bridge trust --for 1h\` to let you
121
- work hands-free until the window closes), then retry the call once. \`GET /approvals\` lists what is waiting.
119
+ - Approve requests while the call is waiting. A returned \`APPROVAL_PENDING\` with status
120
+ \`timeout\` or \`expired\` identifies a closed request: that \`approval_id\` cannot be approved.
121
+ Ask the user to open \`arena-bridge trust --for 1h\` before retrying once, or arrange a fresh
122
+ call that they can approve while it is waiting. \`GET /approvals\` includes historical records; only \`pending\` is actionable.
122
123
  - \`APPROVAL_DENIED\` means the user said no: do not retry, ask what to do instead.
123
124
 
124
125
  ## Rules
@@ -126,8 +127,8 @@ ${trustLine}
126
127
  Reading or writing anything else returns \`PROTECTED\` — do not try to work around it.
127
128
  2. Side-effecting tools (bash, write/edit/delete, process start/kill, actions on the user's own
128
129
  Chrome or on the desktop) may require a local human approval. When the answer contains
129
- \`APPROVAL_PENDING\`, tell the user which approval is pending and stop; they will run
130
- \`arena-bridge approve <approval_id>\` on their machine. Do not retry in a loop.
130
+ \`APPROVAL_PENDING\`, stop and follow the recovery hint; never ask to approve a closed id.
131
+ Do not retry in a loop.
131
132
  3. Work step by step: inspect before you change. Prefer \`read_file\`/\`list_dir\`/\`search_files\`
132
133
  over blind shell commands. \`list_dir\` returns the top level only unless you ask for \`recursive\`.
133
134
  4. Long-running work (dev servers, watchers) belongs in \`start_process\` + \`read_process_output\`,
package/src/service.mjs CHANGED
@@ -1,4 +1,5 @@
1
1
  import fs from 'node:fs';
2
+ import { randomUUID } from 'node:crypto';
2
3
  import os from 'node:os';
3
4
  import path from 'node:path';
4
5
  import { execFileSync } from 'node:child_process';
@@ -44,7 +45,10 @@ export function agentPath() {
44
45
  const bundle = appBundlePath();
45
46
  if (!bundle) return null;
46
47
  const helper = path.join(bundle, 'Contents', 'Helpers', AGENT_NAME);
47
- return fs.existsSync(helper) ? helper : null;
48
+ try {
49
+ fs.accessSync(helper, fs.constants.X_OK);
50
+ return fs.statSync(helper).isFile() ? helper : null;
51
+ } catch { return null; }
48
52
  }
49
53
 
50
54
  /**
@@ -112,6 +116,10 @@ export function programArguments({ bin, domain, authtoken, port } = {}) {
112
116
  return [runnerPath(), 'tunnel', ...extra];
113
117
  }
114
118
 
119
+ function xml(value) {
120
+ return String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
121
+ }
122
+
115
123
  export function plistXml(options = {}) {
116
124
  const logs = logDir();
117
125
  const program = programArguments(options);
@@ -122,15 +130,15 @@ export function plistXml(options = {}) {
122
130
  <key>Label</key><string>${LABEL}</string>
123
131
  <key>ProgramArguments</key>
124
132
  <array>
125
- ${program.map((a) => ` <string>${a}</string>`).join('\n')}
133
+ ${program.map((a) => ` <string>${xml(a)}</string>`).join('\n')}
126
134
  </array>
127
135
  <key>RunAtLoad</key><true/>
128
136
  <key>KeepAlive</key><true/>
129
- <key>StandardOutPath</key><string>${path.join(logs, 'bridge.log')}</string>
130
- <key>StandardErrorPath</key><string>${path.join(logs, 'bridge.err.log')}</string>
137
+ <key>StandardOutPath</key><string>${xml(path.join(logs, 'bridge.log'))}</string>
138
+ <key>StandardErrorPath</key><string>${xml(path.join(logs, 'bridge.err.log'))}</string>
131
139
  <key>EnvironmentVariables</key>
132
140
  <dict>
133
- <key>PATH</key><string>${servicePath()}</string>
141
+ <key>PATH</key><string>${xml(servicePath())}</string>
134
142
  </dict>
135
143
  </dict>
136
144
  </plist>
@@ -152,18 +160,32 @@ export function serviceStatus() {
152
160
  return { installed, running, plist: plistPath(), detail: out.trim().slice(0, 600) };
153
161
  }
154
162
 
163
+ export const reloadScript = "#!/bin/sh\nset -eu\nTARGET=$1\nPLIST=$2\nSTATUS=$3\nJOB=$4\nDOMAIN=${TARGET%/*}\nfinish() {\n code=$?\n trap - EXIT\n if [ \"$code\" -eq 0 ]; then printf 'loaded\\n' > \"$STATUS\"; else printf 'failed (%s)\\n' \"$code\" > \"$STATUS\"; fi\n rm -f \"$0\"\n /bin/launchctl remove \"$JOB\" >/dev/null 2>&1 || true\n exit \"$code\"\n}\ntrap finish EXIT\nprintf 'scheduled\\n' > \"$STATUS\"\nsleep 3\n/bin/launchctl enable \"$TARGET\"\nif /bin/launchctl print \"$TARGET\" >/dev/null 2>&1; then\n /bin/launchctl bootout \"$TARGET\"\nfi\nattempt=0\nuntil /bin/launchctl bootstrap \"$DOMAIN\" \"$PLIST\"; do\n attempt=$((attempt + 1))\n [ \"$attempt\" -lt 10 ] || exit 1\n sleep 1\ndone\n/bin/launchctl print \"$TARGET\" >/dev/null\n";
164
+
155
165
  export function serviceInstall(options = {}) {
156
166
  ensureDirs();
157
167
  fs.mkdirSync(logDir(), { recursive: true });
158
- const dir = path.dirname(plistPath());
159
- fs.mkdirSync(dir, { recursive: true });
168
+ fs.mkdirSync(path.dirname(plistPath()), { recursive: true });
160
169
  fs.writeFileSync(runnerPath(), runnerScript(), { mode: 0o755 });
161
170
  fs.chmodSync(runnerPath(), 0o755);
162
- fs.writeFileSync(plistPath(), plistXml(options));
163
- launchctl(['bootout', `gui/${process.getuid()}/${LABEL}`], { quiet: true });
164
- const out = launchctl(['bootstrap', `gui/${process.getuid()}`, plistPath()], { quiet: true });
165
- launchctl(['enable', `gui/${process.getuid()}/${LABEL}`], { quiet: true });
166
- return { ok: true, plist: plistPath(), detail: (out || '').trim().slice(0, 400) };
171
+ const plist = plistPath();
172
+ fs.writeFileSync(`${plist}.tmp`, plistXml(options), { mode: 0o600 });
173
+ fs.renameSync(`${plist}.tmp`, plist);
174
+ const job = `${LABEL}.reload.${randomUUID()}`;
175
+ const script = path.join(CONFIG_DIR, `${job}.sh`);
176
+ const status = path.join(CONFIG_DIR, 'service-reload.status');
177
+ fs.writeFileSync(script, reloadScript, { mode: 0o700 });
178
+ fs.writeFileSync(status, 'scheduled\n', { mode: 0o600 });
179
+ try {
180
+ execFileSync('launchctl', ['submit', '-l', job, '-o', path.join(logDir(), 'service-reload.log'),
181
+ '-e', path.join(logDir(), 'service-reload.err.log'), '--', '/bin/sh', script,
182
+ `gui/${process.getuid()}/${LABEL}`, plist, status, job], { encoding: 'utf8', timeout: 20000 });
183
+ } catch (e) {
184
+ fs.rmSync(script, { force: true });
185
+ fs.writeFileSync(status, 'submission failed\n');
186
+ return { ok: false, plist, detail: String(e.stderr || e.message).slice(0, 400) };
187
+ }
188
+ return { ok: true, scheduled: true, plist, status, detail: 'reload scheduled; check service status and service-reload.status' };
167
189
  }
168
190
 
169
191
  export function serviceUninstall() {