@forsion/tangu-computer-use 0.5.8

package/scripts/overlay-visible.check.mjs

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+/**
+ * 「虚拟光标 / 边缘光效到底有没有出现在用户屏幕上」的真机仪器。
+ *
+ * 为什么需要它:此前只有几何单测(agent_cursor_tests / agent_highlight_tests)—— 它们证明**算出来的
+ * 坐标**对,却证明不了那个 NSWindow 真的被创建、真的可见、真的盖在目标窗口**上面**。用户报「辅助
+ * 鼠标还是没有出现」时,这三件事差得很远,而我们一直只测了第一件。
+ *
+ * 观测手段:CGWindowListCopyWindowInfo(.optionOnScreenOnly)。
+ *   - **不需要屏幕录制权限**(只有拿窗口标题才需要),所以任何终端都能跑。
+ *   - 返回的数组是**前后顺序**(front-to-back),于是 "叠层的下标 < 目标窗口的下标" 就等价于
+ *     "叠层确实盖在目标之上" —— 这正是 z-order bug 的判定式,光看 isVisible 是看不出来的。
+ *   - 单点采样会被 linger(光效 2s)和动画时机骗过去,所以整段过程按 100ms **时间线采样**。
+ *
+ * **它不证明什么**:只看 NSWindow 的创建/层级/z 序与整窗 alpha。SwiftUI 画布画了个空、光标路径为空、
+ * 局部坐标算错 —— 这些照样能过。要覆盖那一层需要屏幕录制权限去比像素,本脚本刻意不要求那个权限。
+ *
+ * 跑法:node scripts/overlay-visible.check.mjs
+ * 需要:macOS、helper 已装并授权。会短暂打开「计算器」,跑完关掉。
+ */
+import assert from 'node:assert/strict'
+import { execFile, execFileSync, spawn } from 'node:child_process'
+import fs from 'node:fs'
+import { connect } from 'node:net'
+import os from 'node:os'
+import path from 'node:path'
+import { promisify } from 'node:util'
+import { ensureDaemon, freshCalculator, killCalculator, HELPER_EXECUTABLE, SOCK } from './calc-fixture.mjs'
+
+const execFileP = promisify(execFile)
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+
+if (process.platform !== 'darwin') {
+  console.log('overlay check skipped (not macOS)')
+  process.exit(0)
+}
+
+let seq = 0
+function ask(payload) {
+  return new Promise((resolve, reject) => {
+    const sock = connect(SOCK)
+    let buf = ''
+    const timer = setTimeout(() => { sock.destroy(); reject(new Error(`timeout: ${payload.cmd}`)) }, 20_000)
+    sock.on('error', (e) => { clearTimeout(timer); reject(e) })
+    sock.on('data', (d) => {
+      buf += d
+      const nl = buf.indexOf('\n')
+      if (nl < 0) return
+      clearTimeout(timer)
+      sock.end()
+      const msg = JSON.parse(buf.slice(0, nl))
+      if (!msg.ok) return reject(Object.assign(new Error(msg.error?.message || 'helper error'), { code: msg.error?.code }))
+      resolve(msg.result)
+    })
+    sock.write(`${JSON.stringify({ id: `ov_${++seq}`, ...payload })}\n`)
+  })
+}
+
+// ── 探针:按 100ms 采样在屏窗口栈,每次打一行 JSON。数组顺序 = 前后顺序。 ──────────────
+const PROBE_SWIFT = `
+import CoreGraphics
+import Foundation
+
+let seconds = Double(CommandLine.arguments[1]) ?? 6
+let deadline = Date().addingTimeInterval(seconds)
+let start = Date()
+while Date() < deadline {
+    guard let list = CGWindowListCopyWindowInfo([.optionOnScreenOnly, .excludeDesktopElements], kCGNullWindowID) as? [[String: Any]] else { continue }
+    var out: [[String: Any]] = []
+    for (index, info) in list.enumerated() {
+        let b = info[kCGWindowBounds as String] as? [String: Any] ?? [:]
+        out.append([
+            "z": index,
+            "pid": info[kCGWindowOwnerPID as String] as? Int32 ?? 0,
+            "owner": info[kCGWindowOwnerName as String] as? String ?? "",
+            "windowId": info[kCGWindowNumber as String] as? Int ?? 0,
+            "layer": info[kCGWindowLayer as String] as? Int ?? 0,
+            "alpha": info[kCGWindowAlpha as String] as? Double ?? 0,
+            "w": b["Width"] as? Double ?? 0, "h": b["Height"] as? Double ?? 0,
+        ])
+    }
+    let frame: [String: Any] = ["t": Int(Date().timeIntervalSince(start) * 1000), "windows": out]
+    print(String(data: try! JSONSerialization.data(withJSONObject: frame), encoding: .utf8)!)
+    fflush(stdout)
+    Thread.sleep(forTimeInterval: 0.1)
+}
+`
+
+const triple = process.arch === 'x64' ? 'x86_64-apple-macosx14.0' : 'arm64-apple-macosx14.0'
+const swiftFile = path.join(os.tmpdir(), `tangu-cu-overlay-probe-${process.pid}.swift`)
+const probeBin = path.join(os.tmpdir(), `tangu-cu-overlay-probe-${process.pid}`)
+fs.writeFileSync(swiftFile, PROBE_SWIFT)
+execFileSync('xcrun', ['swiftc', '-target', triple, '-O',
+  '-module-cache-path', path.join(os.tmpdir(), `tangu-cu-overlay-cache-${process.arch}`),
+  swiftFile, '-o', probeBin], { stdio: 'inherit' })
+
+/** 后台采样 seconds 秒,返回每帧的窗口栈。 */
+function watch(seconds) {
+  const child = spawn(probeBin, [String(seconds)])
+  const frames = []
+  let buf = ''
+  child.stdout.on('data', (d) => {
+    buf += d
+    let nl
+    while ((nl = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, nl); buf = buf.slice(nl + 1)
+      if (line.trim()) frames.push(JSON.parse(line))
+    }
+  })
+  return { frames, done: new Promise((r) => child.on('close', r)) }
+}
+
+function helperPid() {
+  const out = execFileSync('pgrep', ['-f', HELPER_EXECUTABLE], { encoding: 'utf8' })
+  const pid = Number(out.trim().split('\n')[0])
+  assert.ok(Number.isFinite(pid) && pid > 0, 'helper daemon 没在跑')
+  return pid
+}
+
+const CURSOR_LEVEL = 102 // NSWindow.Level.popUpMenu + 1(见 agent_cursor.swift)
+const GLOW_LEVEL = 3 // NSWindow.Level.floating
+const VISIBLE_ALPHA = 0.5 // 淡入淡出中的窗口不算"用户看得见"
+const overlaysIn = (windowStack, hpid) => {
+  const mine = windowStack.filter((x) => x.pid === hpid && x.alpha > VISIBLE_ALPHA)
+  return { cursor: mine.find((x) => x.layer === CURSOR_LEVEL), glow: mine.find((x) => x.layer === GLOW_LEVEL) }
+}
+
+/**
+ * 等到屏幕上一个叠层都不剩,再开始测。
+ *
+ * ⚠️这一步是**假绿灯防线**:光标空闲 8 秒才自动隐藏,而 check:live 会紧接着 check:liveview 跑 ——
+ * 上一个仪器留下的光标窗口足以让本次的断言通过,哪怕本次这一下压根没画光标。
+ */
+async function waitForCleanSlate(hpid, timeoutMs = 14_000) {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    const w = watch(0.15)
+    await w.done
+    const last = w.frames.at(-1)
+    if (last) {
+      const { cursor, glow } = overlaysIn(last.windows, hpid)
+      if (!cursor && !glow) return
+    }
+    await sleep(500)
+  }
+  throw new Error('等叠层散场超时 —— 上一次的光标还挂在屏上,此时测不出本次有没有画')
+}
+
+const findNode = (node, pred) => {
+  if (!node) return null
+  if (pred(node)) return node
+  for (const c of node.children || []) { const hit = findNode(c, pred); if (hit) return hit }
+  return null
+}
+try {
+  // 先发一条命令 —— daemon 是惰性启动的,没连过就没有进程可 pgrep。
+  const diag = await ensureDaemon(ask)
+  assert.ok(diag.accessibility, '需要「辅助功能」权限')
+  const hpid = helperPid()
+
+  const { calc, win } = await freshCalculator(ask)
+  const look = await ask({ cmd: 'look', pid: calc.pid, windowId: win.windowId, includeImage: true })
+  const five = findNode(look.outline, (x) => x.role === 'AXButton' && (x.description === '5' || x.title === '5'))
+  assert.ok(five, '没找到数字键 5')
+
+  // 干净起跑线:确认此刻一个叠层都没有,后面「出现了」才归功于这一次操作。
+  await waitForCleanSlate(hpid)
+
+  const w = watch(6)
+  await sleep(400) // 这段是基线帧,必须是空的
+  const actStartedAt = Date.now()
+  // policy=background → helper delivery=pid/ax → 这一路**按设计必须**画虚拟光标 + 边缘光效。
+  const acted = await ask({
+    cmd: 'act', lookId: look.lookId, pid: calc.pid, policy: 'background',
+    cursorOverlay: true, action: 'click',
+    target: { x: five.rect.x + five.rect.w / 2, y: five.rect.y + five.rect.h / 2 },
+    params: { button: 'left', clickCount: 1 },
+  })
+  const actMs = Date.now() - actStartedAt
+  await w.done
+
+  console.log(`  performed = ${JSON.stringify(acted.performed)}`)
+  assert.ok(['ax', 'pid'].includes(acted.performed?.delivery),
+    `policy=background 必须走后台投递,实得 delivery=${acted.performed?.delivery}`)
+
+  // ── 时间线归约 ──────────────────────────────────────────────────────────────
+  // ⚠️按 **window level** 分辨,不要按尺寸:关闭中的叠层会带着 alpha≈0.007 淡出好几帧,
+  // 一度被误判成"边缘光效已上屏"而给出假绿灯。level 同时正是这次的修复点,一并钉死。
+  const calcWinId = win.windowId
+  const rows = w.frames.map((f) => {
+    const target = f.windows.find((x) => x.windowId === calcWinId)
+    return { t: f.t, ...overlaysIn(f.windows, hpid), targetZ: target?.z }
+  })
+  const baseline = rows.filter((r) => r.t < 400) // act 发出之前
+  const after = rows.filter((r) => r.t >= 400 + actMs)
+  const glyph = (o, targetZ) => (!o ? '·' : targetZ == null ? '?' : o.z < targetZ ? 'A' : 'b')
+  console.log(`  示意光标: ${rows.map((r) => glyph(r.cursor, r.targetZ)).join('')}`)
+  console.log(`  边缘光效: ${rows.map((r) => glyph(r.glow, r.targetZ)).join('')}`)
+  console.log(`             (· 不在屏上 ｜ A 在目标窗口之上 ｜ b 被目标窗口盖住;前 ${baseline.length} 帧是基线)`)
+  const sample = rows.find((r) => r.cursor)
+  if (sample) console.log(`  示意光标窗口:layer=${sample.cursor.layer} alpha=${sample.cursor.alpha} ${sample.cursor.w}x${sample.cursor.h}`)
+  const glowSample = rows.find((r) => r.glow)
+  if (glowSample) console.log(`  边缘光效窗口:layer=${glowSample.glow.layer} alpha=${glowSample.glow.alpha} ${glowSample.glow.w}x${glowSample.glow.h}`)
+
+  // ⚠️基线必须是空的,否则「出现了」可能是上一个仪器留下的窗口(光标空闲 8 秒才隐藏)。
+  assert.ok(!baseline.some((r) => r.cursor), '动手之前就有示意光标在屏上 —— 这轮的断言会认错功劳')
+  assert.ok(!baseline.some((r) => r.glow), '动手之前就有边缘光效在屏上 —— 这轮的断言会认错功劳')
+
+  assert.ok(after.some((r) => r.cursor), '这一下之后示意光标没出现 —— AgentCursor 的 NSWindow 没被创建/显示')
+  assert.ok(after.some((r) => r.glow), '这一下之后边缘光效没出现 —— AgentHighlight 没被点亮')
+  // 命门:窗口在屏上 ≠ 用户看得见。level 没设的话它待在普通层(layer=0),
+  // 而宿主是 .accessory 从不激活 → 永远被被操控的那个 App 压在下面 = 用户什么也看不到。
+  assert.ok(after.some((r) => r.cursor && r.targetZ != null && r.cursor.z < r.targetZ), '示意光标始终被目标窗口盖住(z-order 在其下)—— 用户看不见,等于没画')
+  assert.ok(after.some((r) => r.glow && r.targetZ != null && r.glow.z < r.targetZ), '边缘光效始终被目标窗口盖住(z-order 在其下)—— 用户看不见,等于没画')
+  console.log('✅ 叠层可见性:这一下之后两个叠层都新上了屏,且都盖在被操控窗口之上')
+  console.log('   (只验证窗口的创建/层级/z 序 —— 画布内容是否真画出了像素,本仪器不覆盖)')
+} finally {
+  await killCalculator(ask).catch(() => {})
+  fs.rmSync(probeBin, { force: true })
+  fs.rmSync(swiftFile, { force: true })
+}

package/scripts/package-macos-app.mjs

@@ -0,0 +1,39 @@
+// Build-time only. All private-key signing is opt-in here, never in setup-helper.
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { appName, bundleId, sealedFiles, sha256, verifyMacosApp } from './macos-bundle.mjs';
+
+export async function packageMacosApp(binary, outputDir, version, signArgs) {
+  const temp = await fs.mkdtemp(path.join(os.tmpdir(), 'cu-package-'));
+  try {
+    const app = path.join(temp, appName);
+    await fs.mkdir(path.join(app, 'Contents/MacOS'), { recursive: true });
+    await fs.copyFile(binary, path.join(app, 'Contents/MacOS/bridge'));
+    await fs.chmod(path.join(app, 'Contents/MacOS/bridge'), 0o755);
+    await fs.writeFile(path.join(app, 'Contents/Info.plist'), `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>CFBundleIdentifier</key><string>${bundleId}</string>
+<key>CFBundleName</key><string>tangu-computer-use</string>
+<key>CFBundleDisplayName</key><string>tangu-computer-use</string>
+<key>CFBundleExecutable</key><string>bridge</string>
+<key>CFBundlePackageType</key><string>APPL</string>
+<key>CFBundleShortVersionString</key><string>${version}</string>
+<key>CFBundleVersion</key><string>${version}</string>
+<key>LSMinimumSystemVersion</key><string>14.0</string>
+<key>LSUIElement</key><true/>
+</dict></plist>\n`);
+    execFileSync('/usr/bin/codesign', [...signArgs, app], { stdio: 'inherit' });
+    verifyMacosApp(app);
+    const archive = path.join(temp, `${appName}.zip`);
+    execFileSync('/usr/bin/ditto', ['-c', '-k', '--keepParent', app, archive], { stdio: 'inherit' });
+    const files = Object.fromEntries(await Promise.all(sealedFiles.map(async file => [file, sha256(await fs.readFile(path.join(app, file)))])));
+    const metadata = { bundleId, version, archiveSha256: sha256(await fs.readFile(archive)), files };
+    await fs.mkdir(outputDir, { recursive: true });
+    await fs.copyFile(archive, path.join(outputDir, `${appName}.zip`));
+    await fs.writeFile(path.join(outputDir, `${appName}.json`), JSON.stringify(metadata, null, 2) + '\n');
+    console.log(`Packaged sealed helper app at ${outputDir}`);
+  } finally { await fs.rm(temp, { recursive: true, force: true }); }
+}

package/scripts/permissions.check.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+// Compile the actual permission methods against fake OS APIs. Never launch the
+// installed helper, query TCC, request capture, or open System Settings in tests.
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const source = fs.readFileSync(path.join(root, 'native/macos/bridge.swift'), 'utf8');
+function method(name) {
+  const start = source.indexOf(`\tprivate func ${name}(`);
+  assert.ok(start >= 0, `missing native method: ${name}`);
+  const end = source.indexOf('\n\t}', start);
+  assert.ok(end > start, `missing method end: ${name}`);
+  return source.slice(start, end + 4).replace('private func', 'func');
+}
+const dispatchStart = source.indexOf('\t\tcase "permissionStatus":');
+const dispatchEnd = source.indexOf('\t\tcase "openPermissionPane":', dispatchStart);
+assert.ok(dispatchStart >= 0 && dispatchEnd > dispatchStart, 'permission command dispatch must exist');
+const dispatch = source.slice(dispatchStart, dispatchEnd);
+const methods = ['permissionStatus', 'systemSettingsWindowBounds', 'checkPermissions', 'registerPermissions', 'boolArg', 'stringArg'].map(method).join('\n');
+
+if (process.platform !== 'darwin') {
+  console.log('native permission checks skipped (not macOS)');
+  process.exit(0);
+}
+
+const harness = String.raw`
+import Foundation
+import CoreGraphics
+
+struct BridgeFailure: Error { let message: String; let code: String }
+struct App { let bundleIdentifier: String; let processIdentifier: Int32 }
+final class NSWorkspace {
+  static let shared = NSWorkspace()
+  var frontmostApplication: App?
+  var runningApplications: [App] = []
+}
+enum Fake {
+  static var ax = false
+  static var preflight = false
+  static var capturable = false
+  static var axReads = 0
+  static var preflightReads = 0
+  static var axRequests = 0
+  static var screenRequests = 0
+  static var probes = 0
+  static var windowReads = 0
+  static var windows: [[String: Any]] = []
+  static func reset() {
+    ax = false; preflight = false; capturable = false
+    axReads = 0; preflightReads = 0; axRequests = 0; screenRequests = 0; probes = 0; windowReads = 0
+    windows = []
+    NSWorkspace.shared.frontmostApplication = nil
+    NSWorkspace.shared.runningApplications = []
+  }
+}
+let kAXTrustedCheckOptionPrompt = Unmanaged.passRetained("prompt" as CFString)
+func AXIsProcessTrusted() -> Bool { Fake.axReads += 1; return Fake.ax }
+func CGPreflightScreenCaptureAccess() -> Bool { Fake.preflightReads += 1; return Fake.preflight }
+func AXIsProcessTrustedWithOptions(_ options: CFDictionary) -> Bool {
+  precondition((options as NSDictionary)["prompt"] as? Bool == true)
+  Fake.axRequests += 1; return Fake.ax
+}
+func CGRequestScreenCaptureAccess() -> Bool { Fake.screenRequests += 1; return Fake.preflight }
+func CGWindowListCopyWindowInfo(_ options: CGWindowListOption, _ window: CGWindowID) -> CFArray? {
+  precondition(options.contains(.optionOnScreenOnly) && window == kCGNullWindowID)
+  Fake.windowReads += 1; return Fake.windows as CFArray
+}
+final class Bridge {
+  let permissionCacheLock = NSLock()
+  var grantedPermissionStatus: [String: Any]?
+  func permissionSource() -> [String: Any] { ["attribution": "helper-app", "pid": 123] }
+  func screenRecordingCapturable() -> Bool { Fake.probes += 1; return Fake.capturable }
+  func command(_ request: [String: Any]) throws -> [String: Any] {
+    let cmd = try stringArg(request, "cmd")
+    switch cmd {
+${dispatch}
+    default: throw BridgeFailure(message: "Unexpected command", code: "unknown_command")
+    }
+  }
+${methods}
+}
+func window(_ pid: Int32, _ rect: CGRect, layer: Int = 0, visible: Bool = true) -> [String: Any] {
+  // No title: this is also the metadata shape before Screen Recording is granted.
+  [kCGWindowOwnerPID as String: pid, kCGWindowLayer as String: layer,
+   kCGWindowIsOnscreen as String: visible, kCGWindowBounds as String: rect.dictionaryRepresentation]
+}
+var passed = 0
+func check(_ condition: @autoclosure () -> Bool, _ label: String) {
+  guard condition() else { fatalError(label) }
+  passed += 1
+}
+
+// Passive status ignores a previous positive capture cache and never prompts.
+Fake.reset()
+let passive = Bridge()
+passive.grantedPermissionStatus = ["accessibility": true, "screenRecording": true]
+Fake.preflight = true
+let status1 = try passive.command(["cmd": "permissionStatus"])
+Fake.preflight = false
+let status2 = try passive.command(["cmd": "permissionStatus"])
+check(status1["accessibility"] as? Bool == false, "status must not use capture cache")
+check(status1["screenRecordingPreflight"] as? Bool == true && status2["screenRecordingPreflight"] as? Bool == false, "status must reread preflight")
+check(Fake.axReads == 2 && Fake.preflightReads == 2, "both preflights run on every status")
+check(Fake.probes == 0 && Fake.axRequests == 0 && Fake.screenRequests == 0, "passive status has no capture or request side effects")
+check(status1["screenRecording"] == nil && status1["screenRecordingCapturable"] == nil, "preflight must not be presented as verified capture")
+check((status1["source"] as? [String: Any])?["attribution"] as? String == "helper-app", "status preserves permission identity")
+check(status1["settingsWindow"] == nil && status1["settingsFrontmost"] as? Bool == false, "absent Settings has no invented bounds")
+
+// Only the largest visible layer-zero window of System Settings is selected.
+let settings = App(bundleIdentifier: "com.apple.systempreferences", processIdentifier: 42)
+NSWorkspace.shared.runningApplications = [App(bundleIdentifier: "other.app", processIdentifier: 8), settings]
+NSWorkspace.shared.frontmostApplication = settings
+let wanted = CGRect(x: -1000, y: -200, width: 850, height: 700)
+Fake.windows = [
+  window(8, CGRect(x: 0, y: 0, width: 5000, height: 5000)),
+  window(42, CGRect(x: 0, y: 0, width: 5000, height: 5000), layer: 1),
+  window(42, CGRect(x: 0, y: 0, width: 5000, height: 5000), visible: false),
+  window(42, CGRect(x: 0, y: 0, width: 0, height: 5000)),
+  window(42, CGRect(x: CGFloat.infinity, y: 0, width: 5000, height: 5000)),
+  window(42, CGRect(x: 10, y: 20, width: 300, height: 200)),
+  window(42, wanted),
+]
+let windowStatus = try passive.command(["cmd": "permissionStatus"])
+let bounds = windowStatus["settingsWindow"] as? [String: CGFloat]
+check(bounds == ["x": -1000, "y": -200, "width": 850, "height": 700], "Settings bounds must use PID/layer/visibility and preserve CG coordinates")
+check(windowStatus["settingsFrontmost"] as? Bool == true, "frontmost uses bundle identity")
+check(Fake.probes == 0 && Fake.axRequests == 0 && Fake.screenRequests == 0, "window metadata requires no grants")
+NSWorkspace.shared.frontmostApplication = App(bundleIdentifier: "other.app", processIdentifier: 8)
+let behind = try passive.command(["cmd": "permissionStatus"])
+check(behind["settingsWindow"] != nil && behind["settingsFrontmost"] as? Bool == false, "visibility and frontmost are separate")
+Fake.windows = []
+let closed = try passive.command(["cmd": "permissionStatus"])
+check(closed["settingsWindow"] == nil, "closed Settings window is omitted")
+
+// Single-kind request isolation; malformed kinds fail before any OS operation.
+Fake.reset()
+let requests = Bridge()
+let axRequest = try requests.command(["cmd": "registerPermissions", "kind": "accessibility"])
+check(Fake.axRequests == 1 && Fake.screenRequests == 0 && Fake.probes == 0, "AX-only request must not request/probe screen capture")
+check(Set(axRequest.keys) == ["accessibility"], "AX-only response cannot claim screen permission")
+Fake.reset()
+let screenRequest = try requests.command(["cmd": "registerPermissions", "kind": "screenRecording"])
+check(Fake.screenRequests == 1 && Fake.axRequests == 0 && Fake.axReads == 0 && Fake.probes == 0, "screen-only request must not touch AX or capture probe")
+check(Set(screenRequest.keys) == ["screenRecording"], "screen request returns request result only")
+for kind: Any in ["invalid", "", 42, NSNull()] {
+  Fake.reset()
+  do {
+    _ = try requests.command(["cmd": "registerPermissions", "kind": kind])
+    fatalError("invalid permission kind was accepted")
+  } catch let error as BridgeFailure {
+    check(error.code == "invalid_args", "invalid kind error code")
+  }
+  check(Fake.axRequests == 0 && Fake.screenRequests == 0 && Fake.probes == 0, "invalid kind must have no side effects")
+}
+Fake.reset()
+Fake.ax = true; Fake.preflight = true; Fake.capturable = true
+let legacy = try requests.command(["cmd": "registerPermissions"])
+check(Fake.axRequests == 1 && Fake.screenRequests == 1 && Fake.probes == 1, "omitted kind retains both legacy requests and probe")
+check(legacy["accessibility"] as? Bool == true && legacy["screenRecordingCapturable"] as? Bool == true, "legacy response preserved")
+
+// Fresh validation must invalidate an old success even when the new check fails.
+Fake.reset()
+Fake.ax = true; Fake.preflight = true; Fake.capturable = true
+let validator = Bridge()
+_ = try validator.command(["cmd": "checkPermissions"])
+Fake.capturable = false
+let cached = try validator.command(["cmd": "checkPermissions", "fresh": false])
+check(cached["screenRecording"] as? Bool == true && Fake.probes == 1, "legacy successful checks remain cached")
+let revoked = try validator.command(["cmd": "checkPermissions", "fresh": true])
+check(revoked["screenRecordingPreflight"] as? Bool == true && revoked["screenRecordingCapturable"] as? Bool == false, "fresh bypasses success despite stale preflight")
+check(validator.grantedPermissionStatus == nil && Fake.probes == 2, "failed fresh check removes stale success")
+_ = try validator.command(["cmd": "checkPermissions"])
+check(Fake.probes == 3, "failure is not cached")
+Fake.capturable = true
+_ = try validator.command(["cmd": "checkPermissions", "fresh": true])
+_ = try validator.command(["cmd": "checkPermissions"])
+check(Fake.probes == 4 && validator.grantedPermissionStatus != nil, "successful fresh check refreshes cache")
+Fake.ax = false
+_ = try validator.command(["cmd": "checkPermissions", "fresh": true])
+check(validator.grantedPermissionStatus == nil, "AX revocation also invalidates success")
+print("permission checks passed: \(passed) assertions (fake OS APIs; no installed helper launched)")
+`;
+
+const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'tangu-cu-permission-tests-'));
+try {
+  const swift = path.join(temporary, 'main.swift');
+  const binary = path.join(temporary, 'permissions-tests');
+  fs.writeFileSync(swift, harness);
+  const triple = process.arch === 'x64' ? 'x86_64-apple-macosx14.0' : 'arm64-apple-macosx14.0';
+  execFileSync('xcrun', ['swiftc', '-target', triple, '-module-cache-path', path.join(os.tmpdir(), `tangu-cu-permission-test-cache-${process.arch}`), swift, '-o', binary], { cwd: root, stdio: 'inherit' });
+  execFileSync(binary, [], { cwd: root, stdio: 'inherit' });
+} finally {
+  fs.rmSync(temporary, { recursive: true, force: true });
+}

package/scripts/platform-contract.check.mjs

@@ -0,0 +1,30 @@
+// Offline platform contract: register definitions only, never run native input or install helpers.
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+if (!process.env.CU_CONTRACT_PLATFORM) {
+  for (const platform of ['darwin', 'win32', 'linux']) {
+    const r = spawnSync(process.execPath, [fileURLToPath(import.meta.url)], {
+      env: { ...process.env, CU_CONTRACT_PLATFORM: platform }, encoding: 'utf8', timeout: 15_000,
+    });
+    assert.equal(r.status, 0, r.stderr || r.error?.message);
+    process.stdout.write(r.stdout);
+  }
+} else {
+  const platform = process.env.CU_CONTRACT_PLATFORM;
+  Object.defineProperty(process, 'platform', { value: platform });
+  let meta;
+  const plugin = (await import('../tangu-plugins/computer-use/dist/index.js')).default;
+  plugin.activate({ registerPlugin: (m) => { meta = m; }, registerCommand() {}, log() {}, sdk: { pluginStore: { isPluginEnabledSync: () => true } } });
+  const visible = meta.toolProvider.tools().filter((t) => t.isEnabledFor({ capabilities: { hostExec: true } }));
+  for (const name of ['find_roots', 'observe_ui', 'search_ui', 'expand_ui', 'inspect_ui', 'act_ui']) assert(visible.some((t) => t.name === name), `${platform}: missing ${name}`);
+  assert.equal(visible.some((t) => t.name === 'ensure_app'), platform === 'darwin');
+  const prompt = meta.promptSection({ execMode: 'host' });
+  assert.match(prompt, /already available|directly callable/i);
+  if (platform !== 'darwin') assert.doesNotMatch(prompt, /call ensure_app first/);
+  const skill = readFileSync(new URL('../skills/computer-use/SKILL.md', import.meta.url), 'utf8');
+  assert.match(skill, /macOS only/);
+  assert.match(skill, /Windows.*Linux/);
+  console.log(`${platform}: Computer Use tool and prompt contract passed`);
+}

package/scripts/setup-helper.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+// macOS runtime setup only installs sealed apps. Certificate discovery/import,
+// private-key signing and native compilation belong exclusively to build time.
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { constants as fsConstants, realpathSync } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveMacosHelperAppPath } from "../src/vendor/platform/macos/helper-path.mjs";
+import { installMacosApp, macosHelperIsCurrent } from "./macos-bundle.mjs";
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const helperAppPath = resolveMacosHelperAppPath();
+const windowsCrateDir = path.join(rootDir, "native", "windows", "bridge-rs");
+const windowsHelperDestPath = process.env.PI_COMPUTER_USE_WINDOWS_HELPER_PATH || path.join(os.homedir(), ".pi", "agent", "helpers", "tangu-computer-use", "windows-bridge.exe");
+const linuxCrateDir = path.join(rootDir, "native", "linux", "bridge-rs");
+const linuxHelperDestPath = process.env.PI_COMPUTER_USE_LINUX_HELPER_PATH || path.join(os.homedir(), ".pi", "agent", "helpers", "tangu-computer-use", "linux-bridge");
+const args = new Set(process.argv.slice(2));
+const isPostinstall = args.has("--postinstall");
+const allowBuildFallback = args.has("--allow-build") || args.has("--runtime") || process.env.PI_COMPUTER_USE_ALLOW_BUILD === "1";
+const allowLinuxBuildFallback = args.has("--allow-build") || process.env.PI_COMPUTER_USE_ALLOW_BUILD === "1";
+
+function getArg(name) {
+  const index = process.argv.indexOf(name);
+  if (index >= 0 && index + 1 < process.argv.length) return process.argv[index + 1];
+}
+function normalizeArch(arch) {
+  if (arch === "arm64" || arch === "x64") return arch;
+  throw new Error(`Unsupported architecture '${arch}'. Supported: arm64, x64.`);
+}
+async function exists(filePath) {
+  try { await fs.access(filePath, fsConstants.F_OK); return true; } catch { return false; }
+}
+async function hashFile(filePath) {
+  return createHash("sha256").update(await fs.readFile(filePath)).digest("hex");
+}
+
+async function copyIfChanged(sourcePath, destinationPath) {
+	const destinationExists = await exists(destinationPath);
+	if (destinationExists) {
+		const [sourceHash, destinationHash] = await Promise.all([hashFile(sourcePath), hashFile(destinationPath)]);
+		if (sourceHash === destinationHash) {
+			await fs.chmod(destinationPath, 0o755);
+			return { changed: false };
+		}
+	}
+
+	await fs.mkdir(path.dirname(destinationPath), { recursive: true });
+	const tempPath = `${destinationPath}.tmp-${process.pid}-${Date.now()}`;
+	await fs.copyFile(sourcePath, tempPath);
+	await fs.chmod(tempPath, 0o755);
+	try {
+		await fs.rename(tempPath, destinationPath);
+	} catch (err) {
+		await fs.rm(tempPath, { force: true }).catch(() => {});
+		if (err.code === "EPERM") {
+			throw new Error(`Cannot update helper at ${destinationPath} — the existing helper process is still running. Close the helper process and re-run this script.`);
+		}
+		throw err;
+	}
+	return { changed: true };
+}
+
+async function run(command, commandArgs) {
+	await new Promise((resolve, reject) => {
+		const child = spawn(command, commandArgs, { stdio: "inherit" });
+		child.on("error", reject);
+		child.on("close", (code) => {
+			if (code === 0) {
+				resolve();
+				return;
+			}
+			reject(new Error(`Command failed (${code}): ${command} ${commandArgs.join(" ")}`));
+		});
+	});
+}
+
+function windowsBinaryPath() {
+	const releaseDir = path.join(windowsCrateDir, "target", "release");
+	return {
+		exePath: path.join(releaseDir, "windows-bridge.exe"),
+		binPath: path.join(releaseDir, "windows-bridge"),
+	};
+}
+
+async function setupWindowsHelper() {
+	const prebuiltPath = path.join(rootDir, "prebuilt", "windows", "windows-bridge.exe");
+	if (await exists(prebuiltPath)) {
+		const { changed } = await copyIfChanged(prebuiltPath, windowsHelperDestPath);
+		console.log(changed
+			? `[tangu-computer-use] installed Windows helper from prebuilt to ${windowsHelperDestPath}`
+			: `[tangu-computer-use] Windows helper already up to date at ${windowsHelperDestPath}`);
+		return;
+	}
+
+	if (allowBuildFallback) {
+		console.log("[tangu-computer-use] Windows prebuilt helper missing; attempting source build with cargo...");
+		await run("cargo", ["build", "--release", "--manifest-path", path.join(windowsCrateDir, "Cargo.toml")]);
+		const { exePath, binPath } = windowsBinaryPath();
+		const cargoOutput = (await exists(exePath)) ? exePath : (await exists(binPath)) ? binPath : exePath;
+		const { changed } = await copyIfChanged(cargoOutput, windowsHelperDestPath);
+		console.log(changed
+			? `[tangu-computer-use] built and installed Windows helper at ${windowsHelperDestPath}`
+			: `[tangu-computer-use] Windows helper already up to date at ${windowsHelperDestPath}`);
+		return;
+	}
+
+	throw new Error(
+		`No Windows prebuilt helper found at ${prebuiltPath}. ` +
+			"Run 'node scripts/build-native.mjs --platform windows' to build, or set PI_COMPUTER_USE_ALLOW_BUILD=1 to build at install time.",
+	);
+}
+
+async function setupLinuxHelper() {
+	const arch = normalizeArch(process.arch);
+	const prebuiltPath = path.join(rootDir, "prebuilt", "linux", arch, "linux-bridge");
+	if (await exists(prebuiltPath)) {
+		const { changed } = await copyIfChanged(prebuiltPath, linuxHelperDestPath);
+		console.log(changed ? `[tangu-computer-use] installed Linux helper (${arch}) from prebuilt to ${linuxHelperDestPath}` : `[tangu-computer-use] Linux helper already up to date at ${linuxHelperDestPath}`);
+		return;
+	}
+	if (allowLinuxBuildFallback) {
+		if (process.platform !== "linux") throw new Error("The Linux helper source fallback must be built on Linux.");
+		console.log("[tangu-computer-use] Linux prebuilt helper missing; attempting source build with cargo...");
+		await run("cargo", ["build", "--release", "--manifest-path", path.join(linuxCrateDir, "Cargo.toml")]);
+		const cargoOutput = path.join(linuxCrateDir, "target", "release", "linux-bridge");
+		const { changed } = await copyIfChanged(cargoOutput, linuxHelperDestPath);
+		console.log(changed ? `[tangu-computer-use] built and installed Linux helper at ${linuxHelperDestPath}` : `[tangu-computer-use] Linux helper already up to date at ${linuxHelperDestPath}`);
+		return;
+	}
+	throw new Error(`No Linux prebuilt helper found for ${arch} at ${prebuiltPath}. Run node scripts/build-native.mjs --platform linux to build, or set PI_COMPUTER_USE_ALLOW_BUILD=1 to build at install time.`);
+}
+
+async function setup() {
+  const explicitPlatform = getArg("--platform");
+  if (explicitPlatform === "windows" || (!explicitPlatform && process.platform === "win32")) return setupWindowsHelper();
+  if (explicitPlatform === "linux" || (!explicitPlatform && process.platform === "linux")) return setupLinuxHelper();
+  if (process.platform !== "darwin") throw new Error("Computer Use helper setup requires macOS, Windows or Linux.");
+  if (args.has("--check")) {
+    // 10 = missing, stale or damaged. Other nonzero exits are package errors.
+    process.exitCode = macosHelperIsCurrent(rootDir, helperAppPath) ? 0 : 10;
+    return;
+  }
+  const changed = await installMacosApp(rootDir, helperAppPath);
+  console.log(`[tangu-computer-use] ${changed ? "installed pre-signed" : "verified current"} helper app at ${helperAppPath}`);
+}
+
+const isMain = process.argv[1] && realpathSync(path.resolve(process.argv[1])) === realpathSync(fileURLToPath(import.meta.url));
+if (isMain) setup().catch(error => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = isPostinstall ? 0 : 1;
+});

package/scripts/tangu-computer-use.entitlements

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "https://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>com.apple.security.device.screen-capture</key>
+    <true/>
+    <key>com.apple.security.automation.apple-events</key>
+    <true/>
+</dict>
+</plist>