@vashp2029/glovebox 0.0.0-stage → 0.3.1

package/bin/glovebox.mjs

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+// glovebox command line: MCP server, CLI sessions, setup, and approvals.
+import fs from "node:fs";
+import { parseArgs } from "node:util";
+import { loadConfig, paths, readUserConfig, VERSION, writeUserConfig } from "../src/config.mjs";
+
+const USAGE = `glovebox ${VERSION} — scriptable computer use for coding agents
+
+Usage:
+  glovebox setup [--rebuild]        Build the helper and ask macOS for permissions
+  glovebox signing [--create]       Make permission grants survive helper rebuilds
+  glovebox doctor                   Check that everything is ready
+  glovebox mcp                      Run the stdio MCP server (tools: js, js_reset)
+  glovebox run [code] [-f file]     Run a script in a persistent CLI session
+        [--session name] [--title t] [--timeout ms]
+                                    Reads code from stdin when no code or file is given.
+                                    Screenshots are saved to files and printed as paths.
+  glovebox reset [--session name]   Drop a CLI session's bindings
+  glovebox stop                     Stop the CLI daemon and its sessions
+  glovebox smoke [--full]           Batched, persistent smoke test on Calculator
+                                    (--full adds background click/drag/scroll in TextEdit)
+  glovebox allow <app>...           Always allow an app (name or bundle id)
+  glovebox deny <app>...            Never allow an app
+  glovebox revoke <app>...          Remove an app from both lists
+  glovebox approval <ask|allowlist|allow-all>
+  glovebox config                   Print the effective configuration
+  glovebox log [-n 20]              Show recent actions
+`;
+
+function die(message) {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}
+
+function printResult(result) {
+  for (const block of result.content ?? []) {
+    if (block.type === "text") process.stdout.write(`${block.text}\n`);
+  }
+  if (!result.ok) process.exitCode = 1;
+}
+
+async function readStdin() {
+  if (process.stdin.isTTY) return "";
+  let data = "";
+  for await (const chunk of process.stdin) data += chunk;
+  return data;
+}
+
+function editList(list, apps, add) {
+  const config = readUserConfig();
+  const lower = apps.map((a) => a.toLowerCase());
+  const next = { ...config };
+  for (const key of ["allow", "deny"]) {
+    next[key] = (config[key] ?? []).filter((entry) => !lower.includes(entry.toLowerCase()));
+  }
+  if (add) next[list] = [...next[list], ...apps];
+  writeUserConfig(next);
+  return next;
+}
+
+async function doctor() {
+  const lines = [];
+  let ok = true;
+  const check = (pass, label, fix) => {
+    lines.push(`${pass ? "ok  " : "FAIL"}  ${label}${!pass && fix ? `\n      ${fix}` : ""}`);
+    if (!pass) ok = false;
+  };
+  const [major, minor] = process.versions.node.split(".").map(Number);
+  check(major > 20 || (major === 20 && minor >= 10), `Node ${process.versions.node} (need 20.10+)`);
+  let config;
+  try {
+    config = loadConfig();
+    check(true, `Config ${fs.existsSync(paths.config) ? paths.config : "(defaults)"}, approval: ${config.approval}`);
+  } catch (error) {
+    check(false, "Config", error.message);
+  }
+  if (process.platform === "darwin") {
+    const helper = await import("../src/macos-helper.mjs");
+    const built = helper.isBuilt();
+    check(built, `Helper built at ${helper.appPath()}`, "Run: glovebox setup");
+    if (built) {
+      const { MacBackend } = await import("../src/backends/macos.mjs");
+      const backend = new MacBackend({ client: "glovebox doctor" });
+      try {
+        const ping = await backend.request("ping");
+        check(true, `Helper running (pid ${ping.pid}, v${ping.version})`);
+        const bg = ping.background ?? {};
+        const bgOk = bg.postEventRecord && bg.setIntegerField && bg.processSerialNumber;
+        lines.push(
+          bgOk
+            ? "ok    Background input available (apps stay in the background)"
+            : `warn  Background input unavailable on this macOS; apps will be brought forward (${Object.entries(bg).filter(([, v]) => !v).map(([k]) => k).join(", ") || "old helper"})`,
+        );
+        const perms = await backend.request("permissions", { prompt: false });
+        check(perms.accessibility, "Accessibility granted to Glovebox Helper", "System Settings > Privacy & Security > Accessibility: enable Glovebox Helper");
+        check(perms.screenRecording, "Screen Recording granted to Glovebox Helper", "System Settings > Privacy & Security > Screen & System Audio Recording: enable Glovebox Helper, then run: glovebox setup --restart");
+        // In testing, Escape only reached the helper with Input Monitoring.
+        lines.push(
+          perms.inputMonitoring
+            ? "ok    Input Monitoring granted: pressing Escape stops a running script"
+            : "info  Input Monitoring not granted (optional): Escape will not stop scripts; switching to another app still does",
+        );
+      } catch (error) {
+        check(false, "Helper reachable", error.message);
+      } finally {
+        backend.close();
+      }
+    }
+  } else {
+    check(false, `Platform ${process.platform}`, "Only macOS has a backend today. See docs/roadmap.md.");
+  }
+  process.stdout.write(`${lines.join("\n")}\n`);
+  if (!ok) process.exitCode = 1;
+}
+
+// Polls the helper until `check(perms)` holds, or gives up after `minutes`.
+async function waitFor(backend, check, minutes = 5) {
+  const deadline = Date.now() + minutes * 60_000;
+  while (Date.now() < deadline) {
+    if (check(await backend.request("permissions", { prompt: false }))) return true;
+    await new Promise((r) => setTimeout(r, 1500));
+  }
+  return false;
+}
+
+// Builds the helper if needed, then walks through the macOS permissions one
+// at a time: macOS drops a second prompt that arrives while the first is open.
+async function setup(flags) {
+  if (process.platform !== "darwin") die(`No backend for ${process.platform} yet. See docs/roadmap.md.`);
+  const helper = await import("../src/macos-helper.mjs");
+  const { MacBackend } = await import("../src/backends/macos.mjs");
+  const say = (text) => process.stdout.write(`${text}\n`);
+  const rebuilding = flags.rebuild || !helper.isBuilt();
+  const hadBuild = fs.existsSync(helper.appPath());
+  if (rebuilding || flags.restart) await helper.quit();
+  if (rebuilding) await helper.build({ log: say });
+  if (rebuilding && hadBuild && !(await helper.signingIdentity())) {
+    // An ad-hoc signed rebuild is a new app to macOS; stale grants keep showing as on.
+    say("The helper was rebuilt ad hoc, so macOS treats it as a new app. If old grants still show as");
+    say("on but this step never finishes, clear them in another terminal and run setup again:");
+    say(`  tccutil reset Accessibility ${helper.BUNDLE_ID}`);
+    say(`  tccutil reset ScreenCapture ${helper.BUNDLE_ID}`);
+    say(`  tccutil reset ListenEvent ${helper.BUNDLE_ID}`);
+    say("To stop this happening on every rebuild: glovebox signing --create");
+  }
+
+  let backend = new MacBackend({ client: "glovebox setup" });
+  let perms = await backend.request("permissions", { prompt: false });
+  if (!perms.accessibility) {
+    say('\n1/2 Accessibility: macOS is asking now. Turn on "Glovebox Helper" in');
+    say("    System Settings > Privacy & Security > Accessibility. Waiting...");
+    await backend.request("permissions", { prompt: true });
+    if (!(await waitFor(backend, (p) => p.accessibility))) die("Timed out waiting for Accessibility. Run glovebox setup again.");
+    say("    Accessibility granted.");
+  }
+  perms = await backend.request("permissions", { prompt: false });
+  if (!perms.screenRecording) {
+    say('\n2/2 Screen Recording: macOS is asking now. Turn on "Glovebox Helper" in');
+    say("    System Settings > Privacy & Security > Screen & System Audio Recording.");
+    say("    If macOS offers to quit and reopen it, accept. If no prompt appears, use + and add");
+    say(`    ${helper.appPath()} (press Cmd+Shift+G in the file picker). Waiting...`);
+    await backend.request("permissions", { prompt: true });
+    if (!(await waitFor(backend, (p) => p.screenRecording))) die("Timed out waiting for Screen Recording. Run glovebox setup again.");
+    say("    Screen Recording granted.");
+    // Relaunch so the key monitor and capture start with the new grants.
+    backend.close();
+    await helper.quit();
+    backend = new MacBackend({ client: "glovebox setup" });
+  }
+  perms = await backend.request("permissions", { prompt: false });
+  if (!perms.inputMonitoring) {
+    say("\nOptional: Input Monitoring lets you stop a running script by pressing Escape.");
+    say("Without it, switching to another app (or js_reset) still stops a script.");
+    say('To enable it, turn on "Glovebox Helper" in System Settings > Privacy & Security >');
+    say(`Input Monitoring (use + and ${helper.appPath()} if it is not listed), then run`);
+    say("`glovebox setup --restart`.");
+    await backend.request("permissions", { prompt: true, inputMonitoring: true });
+  }
+  backend.close();
+  const ready = perms.accessibility && perms.screenRecording;
+  say(ready ? "\nReady. Check with `glovebox doctor`, then try `glovebox smoke`." : "\nNot ready yet; run `glovebox doctor` to see what is missing.");
+  if (!ready) process.exitCode = 1;
+}
+
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  const { values: flags, positionals } = parseArgs({
+    args: rest,
+    allowPositionals: true,
+    options: {
+      file: { type: "string", short: "f" },
+      session: { type: "string", short: "s" },
+      title: { type: "string", short: "t" },
+      timeout: { type: "string" },
+      rebuild: { type: "boolean" },
+      restart: { type: "boolean" },
+      create: { type: "boolean" },
+      full: { type: "boolean" },
+      n: { type: "string", short: "n" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+
+  switch (command) {
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      process.stdout.write(USAGE);
+      return;
+    case "--version":
+    case "-v":
+    case "version":
+      process.stdout.write(`${VERSION}\n`);
+      return;
+    case "mcp": {
+      const { serveMcp } = await import("../src/mcp.mjs");
+      serveMcp();
+      return;
+    }
+    case "daemon": {
+      const { runDaemon } = await import("../src/daemon.mjs");
+      runDaemon();
+      return;
+    }
+    case "run": {
+      const code = flags.file ? fs.readFileSync(flags.file, "utf8") : positionals.join(" ") || (await readStdin());
+      if (!code.trim()) die("glovebox run: no code. Pass it as an argument, with -f file, or on stdin.");
+      const { daemonRequest } = await import("../src/daemon.mjs");
+      printResult(
+        await daemonRequest({
+          op: "run",
+          code,
+          title: flags.title,
+          session: flags.session,
+          timeoutMs: flags.timeout ? Number(flags.timeout) : undefined,
+          client: process.env.GLOVEBOX_CLIENT,
+        }),
+      );
+      return;
+    }
+    case "reset":
+    case "stop": {
+      const { daemonRequest } = await import("../src/daemon.mjs");
+      try {
+        printResult(await daemonRequest({ op: command, session: flags.session }, { autostart: false }));
+      } catch {
+        process.stdout.write("No daemon running.\n");
+      }
+      return;
+    }
+    case "smoke": {
+      const { runSmoke } = await import("../src/smoke.mjs");
+      process.exitCode = (await runSmoke({ full: flags.full })) ? 0 : 1;
+      return;
+    }
+    case "setup":
+      await setup(flags);
+      return;
+    case "signing": {
+      if (process.platform !== "darwin") die("Signing applies to the macOS helper only.");
+      const helper = await import("../src/macos-helper.mjs");
+      let identity = await helper.signingIdentity();
+      if (!identity && flags.create) {
+        await helper.createSigningIdentity({ log: (m) => process.stdout.write(`${m}\n`) });
+        identity = await helper.signingIdentity();
+      }
+      if (identity) {
+        process.stdout.write(`Signing identity "${helper.SIGNING_NAME}" (${identity}) is ready.\n`);
+        process.stdout.write("Run `glovebox setup --rebuild` once to re-sign the helper with it, and grant permissions one last time.\n");
+      } else {
+        process.stdout.write(
+          [
+            "No local signing identity. The helper is signed ad hoc, so every rebuild resets its macOS permissions.",
+            `Create one (a self-signed certificate named "${helper.SIGNING_NAME}" in your login keychain):`,
+            "  glovebox signing --create",
+            "",
+          ].join("\n"),
+        );
+      }
+      return;
+    }
+    case "doctor":
+      await doctor();
+      return;
+    case "allow":
+    case "deny":
+    case "revoke": {
+      if (positionals.length === 0) die(`glovebox ${command}: name at least one app`);
+      const next = editList(command, positionals, command !== "revoke");
+      process.stdout.write(`allow: ${JSON.stringify(next.allow)}\ndeny: ${JSON.stringify(next.deny)}\n`);
+      process.stdout.write("Running sessions keep approvals they already have; js_reset or glovebox reset to re-check.\n");
+      return;
+    }
+    case "approval": {
+      const mode = positionals[0];
+      if (!["ask", "allowlist", "allow-all"].includes(mode)) die("glovebox approval: use ask, allowlist, or allow-all");
+      writeUserConfig({ approval: mode });
+      process.stdout.write(`approval: ${mode}\n`);
+      if (mode === "allow-all") {
+        process.stdout.write("Warning: agents can now control any app without asking, except blocked apps (terminals, password managers, System Settings).\n");
+      }
+      return;
+    }
+    case "config":
+      process.stdout.write(`${JSON.stringify(loadConfig(), null, 2)}\n`);
+      return;
+    case "log": {
+      const n = Number(flags.n ?? 20);
+      const lines = fs.existsSync(paths.log) ? fs.readFileSync(paths.log, "utf8").trim().split("\n").slice(-n) : [];
+      process.stdout.write(lines.length ? `${lines.join("\n")}\n` : "No actions logged yet.\n");
+      return;
+    }
+    default:
+      die(`Unknown command "${command}".\n\n${USAGE}`);
+  }
+}
+
+main().catch((error) => die(error.message));

package/docs/agents.md

@@ -0,0 +1,124 @@
+# Attaching glovebox to an agent
+
+glovebox speaks MCP over stdio (`glovebox mcp`) and also has a CLI
+(`glovebox run`) for agents that can only run shell commands. Both expose the
+same persistent JavaScript session.
+
+Install once, then attach to as many agents as you like:
+
+```bash
+npm install -g github:vpatel9202/glovebox
+glovebox setup     # macOS: builds Glovebox Helper.app and walks through permissions
+glovebox doctor    # everything should say ok
+glovebox smoke     # optional: a real end-to-end check on Calculator
+```
+
+If `glovebox` is not on your PATH (for example, under a version manager), use
+the absolute path from `which glovebox`, or run it as
+`node /path/to/glovebox/bin/glovebox.mjs mcp`.
+
+The MCP server exposes two tools: `js` (run a script) and `js_reset` (drop the
+session). Most agents name them `<server>__js` or `mcp__<server>__js`.
+
+## Claude Code
+
+```bash
+claude mcp add --scope user glovebox -- glovebox mcp
+```
+
+Check with `/mcp` in a session. To teach Claude the loop, copy the skill:
+
+```bash
+mkdir -p ~/.claude/skills && cp -R "$(npm root -g)/@vashp2029/glovebox/skills/glovebox" ~/.claude/skills/
+```
+
+## Grok CLI
+
+Add to `~/.grok/config.toml`, then start a new session:
+
+```toml
+[mcp_servers.glovebox]
+command = "glovebox"
+args = ["mcp"]
+enabled = true
+```
+
+Verify with `grok mcp doctor glovebox`. This config, and the OpenCode and
+Codex ones below, follow each client's documented MCP format but have not been
+exercised end to end. Skill:
+
+```bash
+mkdir -p ~/.grok/skills && cp -R "$(npm root -g)/@vashp2029/glovebox/skills/glovebox" ~/.grok/skills/
+```
+
+## OpenCode
+
+Add to `opencode.json` (project) or `~/.config/opencode/opencode.json` (global):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "glovebox": {
+      "type": "local",
+      "command": ["glovebox", "mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+## Codex CLI
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.glovebox]
+command = "glovebox"
+args = ["mcp"]
+```
+
+## Gemini CLI, Cursor, and other MCP clients
+
+Most clients accept the common `mcpServers` JSON shape:
+
+```json
+{
+  "mcpServers": {
+    "glovebox": { "command": "glovebox", "args": ["mcp"] }
+  }
+}
+```
+
+## Agents without MCP: the CLI
+
+`glovebox run` sends a script to a background daemon that keeps the session
+alive between calls, so bindings persist exactly as they do over MCP.
+
+```bash
+glovebox run 'const calc = await gb.getApp("Calculator"); await calc.typeText("2+2="); await calc.getAXState()'
+glovebox run 'await calc.getAXState()'          # calc is still bound
+glovebox run -f step.js --title "fill form"     # or from a file, or stdin
+glovebox reset                                   # drop the bindings
+```
+
+Screenshots are written to `~/.glovebox/screenshots/` and the path is printed,
+so an agent that can read image files can look at them. Use `--session name`
+to keep separate sessions. The daemon exits after an hour idle
+(`daemon.idleMinutes` in the config).
+
+## Approval prompts
+
+The first time a session touches an app, glovebox shows a native dialog:
+**Allow for This Session**, **Always Allow**, or **Deny**. "Session" means one
+MCP connection or one CLI session. To pre-approve apps without dialogs:
+
+```bash
+glovebox allow Calculator TextEdit
+glovebox approval allowlist   # never prompt; only allowlisted apps work
+```
+
+`glovebox approval allow-all` turns prompts off for every app except the
+blocked ones (terminals, password managers, and a few others). Those need an
+explicit `glovebox allow`. The full list is in
+[SECURITY.md](../SECURITY.md#blocked-apps).

package/docs/api.md

@@ -0,0 +1,150 @@
+# glovebox API
+
+Scripts run in one persistent JavaScript session. Top-level `const`, `let`,
+`function`, `class`, and `await` persist until `js_reset` (MCP) or
+`glovebox reset` (CLI). Redeclaring a name is allowed. `gb` is the entry
+point; `cua` is an alias.
+
+```js
+const calc = await gb.getApp("Calculator");
+await calc.pressKey("Escape");
+await calc.typeText("12*3=");
+await calc.getAXState();
+```
+
+## gb
+
+- `gb.getApp(query, {activate, foreground})` returns an App handle. `query` is
+  a display name, a bundle id, or `"pid:123"`. Launches the app if it is not
+  running, without bringing it to the front unless `activate: true`.
+  `foreground: true` makes every input to the handle use the foreground
+  route; it takes effect only on the call that first creates the handle.
+  The first action in each app may show an approval dialog to the user.
+- `gb.listApps({installed, emit})` lists running apps (or installed ones too)
+  and returns `[{name, bundleId, pid, running, active}]`. It prints the list
+  unless `emit: false`.
+- `gb.sleep(ms)` waits. Also available as `sleep(ms)`.
+- `gb.permissions()` reports Accessibility and Screen Recording status.
+- `help(topic)` prints this document, or the sections mentioning `topic`.
+- `console.log(...)` and `nodeRepl.write(value)` add text to the result. The
+  value of the last expression is added too, unless a read already printed it.
+
+## Reading state
+
+- `app.name`, `app.bundleId`, and `app.pid` identify the handle.
+  `app.view` is `{window, width, height, scale, ...}` for the window last read
+  (`null` before the first read); `scale` is image pixels per screen point.
+- `app.getAXState({disableDiffing, frames, menus, window, maxNodes, maxDepth, emit})`
+  returns the accessibility tree as text. The first read of a window is the
+  full tree; later reads print only lines that changed (`~`), were added
+  (`+`), or a list of removed indices. `disableDiffing: true` prints the full
+  tree. `frames: true` appends `@x,y wxh` in image pixels. `menus: true` adds
+  the menu bar. `window` picks a window index from `app.windows()`.
+  Without `window`, reads and clicks use the focused window if it is a normal
+  one, else the window last used, else the main window; tooltips, popovers,
+  and rename fields never take over. Diffs compare against the last printed
+  read of the same window; `{emit: false}` reads don't change that.
+  `maxNodes` (default 800) and `maxDepth` (default 40) bound the tree; a
+  truncated tree says so.
+- Line format: `<index> <role> "<label>" value="..." id=... help="..."
+  (focused, selected, disabled, settable) actions: ...`. Indentation is depth.
+  Indices are stable for the life of the session, so a diff means what it says.
+- `app.getScreenshot({window, format, quality, emit})` returns
+  `{width, height, mimeType, data}` and adds the image to the result. Over the
+  CLI the image is saved to a file and the path is printed.
+- `app.getAXStateAndScreenshot(options)` does both.
+- `app.windows()` lists windows with their frames and image size.
+- `app.frame(index)` and `app.center(index)` give an element's rectangle or
+  center in image pixels.
+- Every read emits by default. Pass `{emit: false}` to only return the value.
+- `app.waitForChange({timeout, window})` waits silently until the window
+  differs from the last printed read (pixels after a screenshot, the tree
+  after a tree read), then settles. Returns `{changed, ms}`; `changed: false`
+  at the timeout (default 10000 ms). Use it after an action in an app that
+  updates late. A blinking caret counts as a change in pixel mode.
+- `app.settle({timeout, stableFor, window})` waits until two screenshots in a
+  row match (ignoring a blinking caret) and returns `{stable, ms}`. Nothing is
+  printed; read afterwards.
+
+## Coordinates
+
+A target is either an element index (a number) or `[x, y]` in **image
+pixels** of the window: `(0, 0)` is the window's top-left corner, and the
+space is exactly the screenshot's pixels. The scale is fixed by the window
+size and display, so `frames`, `center`, screenshots, and clicks always
+agree, even if no screenshot was taken. The header of each read prints the
+image size. If the window is resized, read again before clicking by pixels.
+
+## Actions
+
+Input stays in the background: the app is not brought to the front, the
+user's real cursor does not move, and a drawn agent cursor shows where each
+action lands. If this macOS or an app can't take background input, glovebox
+brings the app forward instead. `app.lastRoute` says how the last action got
+there: `accessibility`, `background`, `background-skylight` (Chromium and
+Electron), or `foreground`, with " (focus restored)" appended if the app took
+focus and glovebox gave it back. Pass
+`{foreground: true}` to `click`, `doubleClick`, `rightClick`, `pressKey`,
+`typeText`, `scroll`, or `drag`, or `gb.getApp(name, {foreground: true})` for
+every action, for apps that ignore background input (some Java, Tk, and game
+windows).
+
+- `app.click(target, {button, count, modifiers, raw, foreground})`. A plain
+  left click on a button, checkbox, link, or menu item is pressed through
+  accessibility. Anything else is a mouse click sent to the app's window.
+  `raw: true` uses the mouse, except on an open menu's items in the
+  background, which only accessibility reaches. A click on a menu item waits
+  for the menu to close. `modifiers` is a list such as `["shift"]`.
+- `app.doubleClick(target)`, `app.rightClick(target)`.
+- `app.pressKey(keys, {repeat})`. xdotool syntax: `Return`, `Tab`, `Escape`,
+  `BackSpace`, `Delete`, `Up`, `Page_Down`, `F5`, `ctrl+a`, `shift+Tab`,
+  `super+c` (super is Cmd on macOS). Space-separated keys press in sequence:
+  `"ctrl+a BackSpace"`. Keys go to the app's key window.
+- `app.typeText(text)`. Types literal text; `\n` presses Return and `\t`
+  presses Tab.
+- `app.scroll(target, dy = 3, {dx})` or `app.scroll(target, {dy, dx})`.
+  Positive `dy` scrolls down, in lines.
+- `app.drag(from, to)` or `app.drag([[x, y], [x, y], ...])`.
+- `app.setValue(index, value)` sets a field's value directly. Finder file
+  names refuse it (Finder would relabel without renaming); rename with a
+  click on the item, `pressKey("Return")`, `typeText(name)`,
+  `pressKey("Return")`, which works in the background.
+- `app.focus(index)` gives an element keyboard focus.
+- `app.selectText(index, {start, length})` selects text in a field.
+- `app.listActions(index)` and `app.performSecondaryAction(index, name)`
+  run an accessibility action such as `"Show Menu"` or `"Increment"`.
+- `app.activate()` brings the app to the front (rarely needed).
+
+## Approval and stopping
+
+The first time a session touches an app, the user sees a dialog: Allow for
+This Session, Always Allow, or Deny. Terminals, password managers, and System
+Settings are blocked unless the user runs `glovebox allow <app>`. If a script
+brought an app forward and the user switches away, the script stops with a
+"Stopped: ..." message. Background scripts keep running while the user works in
+other apps. Escape stops any script, but only when the user has granted Input
+Monitoring. Do not continue GUI work until the user asks.
+On the foreground route a script brings an app forward at most once per call.
+Every action is appended to `~/.glovebox/actions.log` (typed text is logged
+as a length only).
+
+## Known limits
+
+- **Pop-up menus and your keyboard.** While a background app's pop-up menu is
+  open, macOS menu tracking is system-wide, so what you type goes to that app. A
+  word you type can land in its field. Keep the time the menu is open short: open
+  it and pick the item in one script, with no read in between. A dedicated
+  `app.select(popup, item)` is planned.
+- **Window controls during background typing.** A target window can show active
+  window controls while it receives background keys, even though your app stays
+  frontmost and keeps your keyboard.
+- **One-node trees.** Remote desktops such as Citrix expose a single accessibility
+  node, so work there runs on screenshots and pixel clicks.
+
+## Tips
+
+- Bind each app once and reuse the handle; define helpers in the session.
+- Batch a whole step into one call: several actions, then one read.
+- Read the tree first. Use screenshots only when the tree has nothing useful
+  (remote desktops such as Citrix, canvases, games) or you need to see layout.
+- When the tree is a single node, work in pixels from the latest screenshot.