@vashp2029/glovebox 0.0.0-stage → 0.3.0

package/src/kernel.mjs

@@ -0,0 +1,217 @@
+// The persistent session. Runs as its own process so the host (MCP server or
+// CLI daemon) can stop a runaway script without going down with it.
+//
+// stdin:  {"id": n, "op": "eval", "code": "...", "title": "..."} | {"op": "abort"}
+// stdout: {"id": n, "ok": bool, "content": [{type: "text"|"image", ...}]}
+import fs from "node:fs";
+import path from "node:path";
+import util from "node:util";
+import vm from "node:vm";
+import { fileURLToPath } from "node:url";
+import { createApi } from "./api.mjs";
+import { createBackend } from "./backends/index.mjs";
+import { loadConfig, paths } from "./config.mjs";
+import { transformCell } from "./transform.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const client = process.env.GLOVEBOX_CLIENT || "An agent";
+const imageMode = process.env.GLOVEBOX_IMAGE_MODE === "file" ? "file" : "inline";
+
+// Anything a dependency prints must not corrupt the protocol on stdout.
+const protocolOut = process.stdout.write.bind(process.stdout);
+process.stdout.write = (chunk, ...rest) => process.stderr.write(chunk, ...rest);
+
+function send(message) {
+  protocolOut(`${JSON.stringify(message)}\n`);
+}
+
+class StoppedError extends Error {
+  constructor(reason) {
+    super(reason);
+    this.name = "Stopped";
+  }
+}
+
+let config = loadConfig();
+let content = [];
+// Text the API already printed this cell (reads, help). Returning or logging
+// the same value again must not print it twice.
+let printed = new Set();
+let running = false;
+let abortReason = null;
+let cellTitle = null;
+let cellNumber = 0;
+
+function pushText(text) {
+  if (!running || text === "") return;
+  const last = content.at(-1);
+  if (last?.type === "text") last.text += `\n${text}`;
+  else content.push({ type: "text", text });
+}
+
+function show(value) {
+  return typeof value === "string" ? value : util.inspect(withoutPrinted(value), { depth: 4, maxArrayLength: 50, maxStringLength: 4000, breakLength: 120 });
+}
+
+// A copy of `value` with already-printed strings replaced by a marker, e.g.
+// the `text` of getAXStateAndScreenshot().
+function withoutPrinted(value, depth = 0) {
+  if (typeof value === "string") return printed.has(value) ? "[printed above]" : value;
+  if (depth > 4 || value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map((v) => withoutPrinted(v, depth + 1));
+  if (Object.getPrototypeOf(value) !== Object.prototype) return value;
+  return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, withoutPrinted(v, depth + 1)]));
+}
+
+const out = {
+  text(value) {
+    const text = show(value);
+    pushText(text);
+    if (running) printed.add(text);
+  },
+  async image(data, mimeType, label) {
+    if (!running) return;
+    if (imageMode === "file") {
+      fs.mkdirSync(paths.shots, { recursive: true, mode: 0o700 });
+      const ext = mimeType === "image/jpeg" ? "jpg" : "png";
+      const safe = label.replace(/[^A-Za-z0-9._-]+/g, "_");
+      const file = path.join(paths.shots, `${new Date().toISOString().replace(/[:.]/g, "-")}-${safe}.${ext}`);
+      fs.writeFileSync(file, Buffer.from(data, "base64"));
+      pushText(`Image saved: ${file}`);
+    } else {
+      content.push({ type: "image", mimeType, data });
+    }
+  },
+};
+
+function log(entry) {
+  if (!config.log.enabled) return;
+  try {
+    fs.mkdirSync(paths.home, { recursive: true, mode: 0o700 });
+    fs.appendFileSync(paths.log, `${JSON.stringify({ ts: new Date().toISOString(), client, step: cellTitle ?? undefined, ...entry })}\n`, { mode: 0o600 });
+  } catch {
+    // Logging must never break an action.
+  }
+}
+
+function help(topic) {
+  const doc = fs.readFileSync(path.join(here, "..", "docs", "api.md"), "utf8");
+  if (!topic) return doc;
+  const sections = doc.split(/^(?=## )/m);
+  const hit = sections.filter((s) => s.toLowerCase().includes(String(topic).toLowerCase()));
+  return hit.length ? hit.join("\n") : `No help for "${topic}". Call help() for everything.`;
+}
+
+const backend = createBackend({ client });
+backend.on("escape", () => {
+  if (running) abortReason = "Stopped: the user pressed Escape. Do not continue GUI actions until the user asks.";
+});
+
+const ctx = {
+  backend,
+  get config() {
+    return config;
+  },
+  out,
+  log,
+  help,
+  get cell() {
+    return cellNumber;
+  },
+  checkAbort() {
+    if (abortReason) throw new StoppedError(abortReason);
+  },
+  stop(reason) {
+    abortReason = reason;
+    throw new StoppedError(reason);
+  },
+  settle() {
+    return new Promise((resolve) => setTimeout(resolve, config.settleMs ?? 80));
+  },
+};
+
+function makeContext() {
+  const gb = createApi(ctx);
+  const consoleProxy = Object.fromEntries(
+    ["log", "info", "warn", "error", "debug"].map((name) => [
+      name,
+      (...args) => pushText(args.filter((a) => !(typeof a === "string" && printed.has(a))).map(show).join(" ")),
+    ]),
+  );
+  const sandbox = {
+    gb,
+    cua: gb,
+    help: gb.help,
+    sleep: gb.sleep,
+    console: consoleProxy,
+    nodeRepl: { write: (value) => out.text(value) },
+    setTimeout,
+    clearTimeout,
+    setInterval,
+    clearInterval,
+    queueMicrotask,
+    structuredClone,
+    URL,
+    TextEncoder,
+    TextDecoder,
+    Buffer,
+    fetch,
+    process: { platform: process.platform, env: {} },
+  };
+  return vm.createContext(sandbox, { name: "glovebox" });
+}
+
+let context = makeContext();
+
+async function runCell(message) {
+  content = [];
+  printed = new Set();
+  cellNumber += 1;
+  running = true;
+  abortReason = null;
+  cellTitle = message.title || null;
+  config = loadConfig();
+  try {
+    const code = transformCell(String(message.code ?? ""));
+    const result = await vm.runInContext(code, context, { filename: "cell.js", timeout: 30_000 });
+    if (result !== undefined && typeof result !== "function" && !(typeof result === "string" && printed.has(result))) {
+      pushText(show(result));
+    }
+    send({ id: message.id, ok: true, content });
+  } catch (error) {
+    const text =
+      error instanceof Error
+        ? error.name === "Stopped" || error.name === "SyntaxError"
+          ? error.message
+          : `${error.name}: ${error.message}`
+        : `Thrown: ${show(error)}`;
+    pushText(text);
+    send({ id: message.id, ok: false, content });
+  } finally {
+    running = false;
+    cellTitle = null;
+  }
+}
+
+let chain = Promise.resolve();
+let buffer = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  buffer += chunk;
+  let newline;
+  while ((newline = buffer.indexOf("\n")) >= 0) {
+    const line = buffer.slice(0, newline);
+    buffer = buffer.slice(newline + 1);
+    if (!line) continue;
+    const message = JSON.parse(line);
+    if (message.op === "abort") {
+      if (running) abortReason = message.reason || "Stopped: the script timed out.";
+    } else if (message.op === "eval") {
+      chain = chain.then(() => runCell(message));
+    }
+  }
+});
+process.stdin.on("end", () => process.exit(0));
+process.on("unhandledRejection", (error) => {
+  process.stderr.write(`glovebox kernel: unhandled rejection: ${error?.stack ?? error}\n`);
+});

package/src/keys.mjs

@@ -0,0 +1,96 @@
+// xdotool-style key chords ("ctrl+a", "super+c", "Return", "shift+Tab") parsed
+// into a platform-neutral form. Backends map `key` names to native key codes.
+
+const MODIFIERS = {
+  ctrl: "ctrl",
+  control: "ctrl",
+  shift: "shift",
+  alt: "alt",
+  option: "alt",
+  opt: "alt",
+  meta: "super",
+  super: "super",
+  cmd: "super",
+  command: "super",
+  win: "super",
+  fn: "fn",
+};
+
+// Canonical names; anything else of length 1 is a literal character.
+const NAMES = {
+  return: "Return",
+  enter: "Return",
+  kp_enter: "KP_Enter",
+  tab: "Tab",
+  escape: "Escape",
+  esc: "Escape",
+  space: "space",
+  backspace: "BackSpace",
+  delete: "Delete",
+  del: "Delete",
+  forward_delete: "Delete",
+  insert: "Insert",
+  home: "Home",
+  end: "End",
+  page_up: "Page_Up",
+  pageup: "Page_Up",
+  prior: "Page_Up",
+  page_down: "Page_Down",
+  pagedown: "Page_Down",
+  next: "Page_Down",
+  up: "Up",
+  down: "Down",
+  left: "Left",
+  right: "Right",
+  minus: "minus",
+  plus: "plus",
+  equal: "equal",
+  comma: "comma",
+  period: "period",
+  slash: "slash",
+  backslash: "backslash",
+  semicolon: "semicolon",
+  apostrophe: "apostrophe",
+  grave: "grave",
+  bracketleft: "bracketleft",
+  bracketright: "bracketright",
+  caps_lock: "Caps_Lock",
+};
+
+for (let n = 1; n <= 20; n++) NAMES[`f${n}`] = `F${n}`;
+
+export function parseChord(chord) {
+  if (typeof chord !== "string" || chord.length === 0) {
+    throw new TypeError("pressKey expects a key such as \"Return\" or \"ctrl+a\"");
+  }
+  // "ctrl++" means ctrl and the plus key.
+  const parts = chord === "+" ? ["+"] : chord.replace(/\+\+$/, "+plus").split("+").filter(Boolean);
+  const mods = [];
+  let key = null;
+  for (const [i, raw] of parts.entries()) {
+    const lower = raw.toLowerCase();
+    if (i < parts.length - 1) {
+      const mod = MODIFIERS[lower];
+      if (!mod) throw new TypeError(`Unknown modifier "${raw}" in "${chord}"`);
+      if (!mods.includes(mod)) mods.push(mod);
+      continue;
+    }
+    if (MODIFIERS[lower] && parts.length === 1) {
+      // A bare modifier press.
+      key = MODIFIERS[lower];
+    } else if (NAMES[lower]) {
+      key = NAMES[lower];
+    } else if ([...raw].length === 1) {
+      key = raw;
+    } else {
+      throw new TypeError(`Unknown key "${raw}" in "${chord}"`);
+    }
+  }
+  return { key, mods };
+}
+
+// Accepts "ctrl+a", "ctrl+a ctrl+c" (space-separated sequence), or an array.
+export function parseKeys(input) {
+  const list = Array.isArray(input) ? input : String(input).trim().split(/\s+/);
+  return list.map(parseChord);
+}

package/src/macos-helper.mjs

@@ -0,0 +1,164 @@
+// Builds and launches "Glovebox Helper.app", the macOS backend.
+//
+// The helper is its own app bundle (not a child of the agent) so that macOS
+// attributes Accessibility and Screen Recording to it. One grant then covers
+// every agent and terminal on the machine.
+import { createHash, randomBytes } from "node:crypto";
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import { homeDir, VERSION } from "./config.mjs";
+
+const run = promisify(execFile);
+const here = path.dirname(fileURLToPath(import.meta.url));
+export const HELPER_SOURCE = path.join(here, "..", "native", "macos", "GloveboxHelper.swift");
+export const BUNDLE_ID = "io.github.vpatel9202.glovebox.helper";
+
+export function appPath() {
+  return path.join(homeDir(), "Glovebox Helper.app");
+}
+
+export function socketPath() {
+  return process.env.GLOVEBOX_SOCKET || path.join(homeDir(), "helper.sock");
+}
+
+// Keyed on the helper source only: macOS ties privacy grants to the build,
+// so the helper is rebuilt only when its own code changes.
+function sourceHash() {
+  return createHash("sha256").update(fs.readFileSync(HELPER_SOURCE)).digest("hex").slice(0, 16);
+}
+
+function stampPath() {
+  return path.join(appPath(), "Contents", "Resources", "build-stamp");
+}
+
+export function isBuilt() {
+  try {
+    return fs.readFileSync(stampPath(), "utf8").trim() === sourceHash();
+  } catch {
+    return false;
+  }
+}
+
+function infoPlist() {
+  return `<?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>${BUNDLE_ID}</string>
+  <key>CFBundleName</key><string>Glovebox Helper</string>
+  <key>CFBundleDisplayName</key><string>Glovebox Helper</string>
+  <key>CFBundleExecutable</key><string>glovebox-helper</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/>
+  <key>NSHighResolutionCapable</key><true/>
+</dict>
+</plist>
+`;
+}
+
+// macOS ties privacy grants to the helper's designated requirement. An ad-hoc
+// signature's requirement is the binary's hash, so every rebuild loses the
+// grants. Signing with a local certificate makes the requirement
+// "identifier + certificate", which survives rebuilds. The certificate does not
+// need to be trusted for this; it only needs to be the same one each time.
+export const SIGNING_NAME = "glovebox local signing";
+
+// SHA-1 of the local signing identity, or null. Untrusted identities count.
+export async function signingIdentity() {
+  try {
+    const { stdout } = await run("security", ["find-identity", "-p", "codesigning"]);
+    const line = stdout.split("\n").find((l) => l.includes(`"${SIGNING_NAME}"`));
+    return line?.match(/\b([0-9A-F]{40})\b/)?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// Creates the signing identity in the login keychain. Run only on the user's
+// request (`glovebox signing --create`); it adds a key to their keychain.
+export async function createSigningIdentity({ log = () => {} } = {}) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "glovebox-signing-"));
+  try {
+    const key = path.join(dir, "key.pem");
+    const cert = path.join(dir, "cert.pem");
+    const p12 = path.join(dir, "identity.p12");
+    const pass = randomBytes(16).toString("hex");
+    await run("/usr/bin/openssl", [
+      "req", "-x509", "-newkey", "rsa:2048", "-keyout", key, "-out", cert, "-days", "3650", "-nodes",
+      "-subj", `/CN=${SIGNING_NAME}`,
+      "-addext", "extendedKeyUsage=critical,codeSigning",
+      "-addext", "keyUsage=critical,digitalSignature",
+      "-addext", "basicConstraints=critical,CA:false",
+    ]);
+    await run("/usr/bin/openssl", ["pkcs12", "-export", "-inkey", key, "-in", cert, "-out", p12, "-passout", `pass:${pass}`, "-name", SIGNING_NAME]);
+    // -T lets codesign use the key without a keychain prompt on every build.
+    await run("security", ["import", p12, "-k", path.join(os.homedir(), "Library", "Keychains", "login.keychain-db"), "-P", pass, "-T", "/usr/bin/codesign"]);
+    log(`Created "${SIGNING_NAME}" in your login keychain.`);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// Compiles the helper with the Xcode command line tools and signs it with the
+// local signing identity when there is one, else ad hoc.
+export async function build({ log = () => {} } = {}) {
+  try {
+    await run("xcrun", ["--find", "swiftc"]);
+  } catch {
+    throw new Error("swiftc not found. Install the Xcode command line tools: xcode-select --install");
+  }
+  const app = appPath();
+  const macos = path.join(app, "Contents", "MacOS");
+  const resources = path.join(app, "Contents", "Resources");
+  fs.mkdirSync(macos, { recursive: true });
+  fs.mkdirSync(resources, { recursive: true });
+  fs.writeFileSync(path.join(app, "Contents", "Info.plist"), infoPlist());
+  log("Compiling Glovebox Helper (about a minute)...");
+  const binary = path.join(macos, "glovebox-helper");
+  await run("xcrun", ["swiftc", "-O", "-swift-version", "5", HELPER_SOURCE, "-o", binary], {
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  const identity = await signingIdentity();
+  await run("codesign", ["--force", "--sign", identity ?? "-", "--identifier", BUNDLE_ID, app]);
+  log(identity ? `Signed with "${SIGNING_NAME}"; permission grants survive rebuilds.` : "Signed ad hoc; a rebuild will need permissions granted again (see: glovebox signing).");
+  fs.writeFileSync(stampPath(), `${sourceHash()}\n`);
+  log(`Built ${app}`);
+  return app;
+}
+
+// Starts the helper through LaunchServices so it is its own responsible process.
+export async function launch({ requestPermissions = false } = {}) {
+  const args = ["-g", "-j", "-a", appPath()];
+  for (const name of ["GLOVEBOX_HOME", "GLOVEBOX_APPROVAL", "GLOVEBOX_SOCKET"]) {
+    if (process.env[name]) args.push("--env", `${name}=${process.env[name]}`);
+  }
+  if (requestPermissions) args.push("--args", "--request-permissions");
+  await run("open", args);
+}
+
+// Stops the helper and waits for it to exit, so the next client does not
+// connect to a process that is shutting down.
+export async function quit() {
+  const pattern = path.join(appPath(), "Contents", "MacOS", "glovebox-helper");
+  try {
+    await run("pkill", ["-f", pattern]);
+  } catch {
+    return; // Not running.
+  }
+  for (let i = 0; i < 50; i++) {
+    try {
+      await run("pgrep", ["-f", pattern]);
+    } catch {
+      break; // Gone.
+    }
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  fs.rmSync(socketPath(), { force: true });
+}

package/src/mcp.mjs

@@ -0,0 +1,126 @@
+// stdio MCP server exposing one persistent session as `js` and `js_reset`.
+import { VERSION } from "./config.mjs";
+import { loadConfig } from "./config.mjs";
+import { Session } from "./session.mjs";
+
+const PROTOCOLS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+
+export const JS_DESCRIPTION = `Run JavaScript in a persistent computer-use session. Put a whole step in one call: several actions, then one read. Top-level const/let/function/await persist across calls until js_reset (redeclaring is fine).
+
+const calc = await gb.getApp("Calculator");   // name, bundle id, or "pid:123"; launches if needed, does not steal focus
+await calc.pressKey("Escape");                 // xdotool syntax: Return, Tab, ctrl+a, super+c (super = Cmd)
+await calc.typeText("12*3=");                  // "\\n" presses Return
+await calc.getAXState();                       // text accessibility tree; later reads return only changes
+
+Reads: getAXState({disableDiffing, frames, menus, window}) returns "<index> <role> \\"label\\" value=..." lines. frames:true adds @x,y wxh in image pixels. getScreenshot() and getAXStateAndScreenshot() are the only calls that return an image. Every read emits its output; pass {emit:false} to just get the value.
+Actions: click(target, {button, count, modifiers}), doubleClick, rightClick, scroll(target, dy), drag(from, to), setValue(index, v), focus(index), selectText(index, {start, length}), performSecondaryAction(index, "Show Menu"), listActions(index), activate(), windows(), frame(index), center(index).
+A target is an element index from the tree, or [x, y] pixels in the window image (same space as the screenshot and frames). Prefer indices; use pixels when the tree has nothing useful (remote desktops, canvases). Input stays in the background (focus and the user's cursor don't move); pass {foreground: true} to an action if an app ignores it.
+gb.listApps() lists running apps. console.log adds text to the result. help() or help("click") prints the full API. If a result says "Stopped:" the user took over (switched apps or pressed Escape): stop and ask before continuing.`;
+
+const TOOLS = [
+  {
+    name: "js",
+    description: JS_DESCRIPTION,
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        code: { type: "string", description: "JavaScript to run. Top-level await is supported." },
+        title: { type: "string", description: "A few words naming this step, for the action log." },
+        timeout_ms: { type: "integer", description: "Time limit in milliseconds (default 120000)." },
+      },
+      required: ["code"],
+    },
+  },
+  {
+    name: "js_reset",
+    description: "Restart the session and drop every binding. Use when a script is stuck or you want a clean slate.",
+    inputSchema: { type: "object", additionalProperties: false, properties: {} },
+  },
+];
+
+export function serveMcp({ input = process.stdin, output = process.stdout } = {}) {
+  let session = null;
+  let clientName = "An agent";
+
+  const write = (message) => output.write(`${JSON.stringify(message)}\n`);
+  const reply = (id, result) => write({ jsonrpc: "2.0", id, result });
+  const fail = (id, code, message) => write({ jsonrpc: "2.0", id, error: { code, message } });
+
+  async function call(name, args) {
+    if (name === "js_reset") {
+      session?.reset();
+      return { content: [{ type: "text", text: "Session reset. All bindings are gone." }], isError: false };
+    }
+    if (name !== "js") throw Object.assign(new Error(`Unknown tool ${name}`), { rpc: -32602 });
+    if (typeof args?.code !== "string" || !args.code.trim()) {
+      return { content: [{ type: "text", text: "js needs non-empty code" }], isError: true };
+    }
+    session ??= new Session({ client: clientName, imageMode: "inline" });
+    const timeoutMs = Number.isInteger(args.timeout_ms) && args.timeout_ms > 0 ? args.timeout_ms : loadConfig().timeoutMs;
+    const result = await session.run(args.code, { title: args.title, timeoutMs });
+    const content = result.content?.length ? result.content : [{ type: "text", text: result.ok ? "(no output)" : "Script failed" }];
+    return { content, isError: !result.ok };
+  }
+
+  async function handle(message) {
+    const { id, method, params } = message;
+    const isRequest = Object.hasOwn(message, "id") && method;
+    try {
+      switch (method) {
+        case "initialize": {
+          clientName = params?.clientInfo?.name || clientName;
+          const requested = params?.protocolVersion;
+          reply(id, {
+            protocolVersion: PROTOCOLS.includes(requested) ? requested : PROTOCOLS[0],
+            capabilities: { tools: {} },
+            serverInfo: { name: "glovebox", version: VERSION },
+            instructions:
+              "glovebox drives desktop apps through one persistent JavaScript session. Use the js tool for every GUI step and batch several actions per call.",
+          });
+          return;
+        }
+        case "ping":
+          if (isRequest) reply(id, {});
+          return;
+        case "tools/list":
+          reply(id, { tools: TOOLS });
+          return;
+        case "tools/call":
+          reply(id, await call(params?.name, params?.arguments ?? {}));
+          return;
+        default:
+          if (isRequest) fail(id, -32601, `Method not found: ${method}`);
+      }
+    } catch (error) {
+      if (isRequest) fail(id, error.rpc ?? -32603, error.message);
+    }
+  }
+
+  let buffer = "";
+  input.setEncoding("utf8");
+  input.on("data", (chunk) => {
+    buffer += chunk;
+    let newline;
+    while ((newline = buffer.indexOf("\n")) >= 0) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      if (!line) continue;
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        fail(null, -32700, "Parse error");
+        continue;
+      }
+      void handle(message);
+    }
+  });
+  const shutdown = () => {
+    session?.close();
+    process.exit(0);
+  };
+  input.on("end", shutdown);
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+}