@vortex-os/computer-use 0.1.0

package/scripts/mcp-stdio.mjs

@@ -0,0 +1,546 @@
+#!/usr/bin/env node
+// computer-use — MCP stdio server (PoC). Exposes the CLI dispatcher (action-ext.mjs) as MCP tools.
+// Same backend logic (OS-native). Tools: probe · read_ui · capture_screen.
+// Depends on: @modelcontextprotocol/sdk (pulled in by memory-extended, present in the instance node_modules).
+//   In the real add-on this ships packaged as scripts/mcp-stdio.mjs + bin vortex-mcp-action (design §21).
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { spawnSync, spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { readFileSync, unlinkSync, statSync, mkdtempSync, rmSync, existsSync, mkdirSync, writeFileSync, appendFileSync } from 'node:fs';
+import { tmpdir, homedir } from 'node:os';
+import { createHmac, randomBytes } from 'node:crypto';
+
+const dir = dirname(fileURLToPath(import.meta.url));
+const plat = process.platform;
+
+// ── redaction config (§8·§14) ─────────────────────────────────────────────
+// Normalize the denylist into env (JSON array) so children (worker / per-call spawn) inherit it -> no per-call args. Config source: env > config file.
+// The actual blocking is done by the backend (lib.ps1 Test-AxDenylist) right before CopyFromScreen (Node doesn't know which windows are inside the region/monitor).
+function loadRedactionConfig() {
+  let titles = [], procs = [];
+  try {
+    const cfgPath = join(dir, 'computer-use.config.json');
+    if (existsSync(cfgPath)) {
+      const r = (JSON.parse(readFileSync(cfgPath, 'utf8')) || {}).redaction || {};
+      if (Array.isArray(r.denyWindowTitles)) titles = r.denyWindowTitles;
+      if (Array.isArray(r.denyProcesses)) procs = r.denyProcesses;
+    }
+  } catch {}
+  try { if (process.env.VORTEX_CU_DENY_TITLES) titles = JSON.parse(process.env.VORTEX_CU_DENY_TITLES); } catch {}
+  try { if (process.env.VORTEX_CU_DENY_PROCS) procs = JSON.parse(process.env.VORTEX_CU_DENY_PROCS); } catch {}
+  titles = (Array.isArray(titles) ? titles : []).map(String).filter(Boolean);
+  procs = (Array.isArray(procs) ? procs : []).map(String).filter(Boolean);
+  process.env.VORTEX_CU_DENY_TITLES = JSON.stringify(titles);   // re-export for child inheritance (after normalization)
+  process.env.VORTEX_CU_DENY_PROCS = JSON.stringify(procs);
+  return { titles, procs };
+}
+const REDACTION = loadRedactionConfig();
+
+// ── audit log (§8: metadata/HMAC only, original image not stored) ──────────────────────
+// Location = under LocalAppData (outside the instance data/ -> won't leak via corporate sync, codex MEDIUM). The key lives there too.
+const AUDIT_DIR = join(process.env.LOCALAPPDATA || join(homedir(), '.local', 'share'), 'vortex-computer-use', 'audit');
+function loadAuditKey() {
+  try {
+    mkdirSync(AUDIT_DIR, { recursive: true });
+    const kp = join(AUDIT_DIR, '.hmac-key');
+    if (existsSync(kp)) { const k = readFileSync(kp, 'utf8').trim(); if (k) return k; }
+    const k = randomBytes(32).toString('hex');
+    writeFileSync(kp, k, { mode: 0o600 });   // Windows ignores mode, but LocalAppData is per-user
+    return k;
+  } catch (e) {
+    // Auditing is a record, not an access control — a failed key setup must not block perception (capture); local tool availability. But don't swallow it silently — warn (codex r2 MEDIUM).
+    process.stderr.write(`[computer-use MCP] WARNING: audit log disabled — could not set up HMAC key (${(e && e.message) || e}). Perception still works; captures will NOT be audited.\n`);
+    return null;
+  }
+}
+const AUDIT_KEY = loadAuditKey();
+function auditHmac(buf) { return createHmac('sha256', AUDIT_KEY).update(buf).digest('hex'); }
+function auditLog(tool, payload, imageItems) {
+  if (!AUDIT_KEY) return;   // skip silently if key setup failed (the tool keeps working)
+  try {
+    const p = payload || {};
+    // Detect not only top-level redacted/partialRedacted but also the nested captures[].redacted of a multi-frame watch (codex r3 MEDIUM).
+    const isRed = !!(p.redacted || p.partialRedacted || (Array.isArray(p.captures) && p.captures.some((f) => f && f.redacted)));
+    const rec = {
+      ts: new Date().toISOString(), tool,
+      mode: typeof p.target === 'string' ? p.target : undefined,
+      titleHmac: p.window ? auditHmac(String(p.window)).slice(0, 16) : undefined,   // window title not stored in plaintext (HMAC only, A4-1)
+      redacted: isRed, reason: p.reason || undefined,
+      outputBytes: 0, contentHmac: undefined,
+    };
+    const h = createHmac('sha256', AUDIT_KEY);
+    if (imageItems && imageItems.length) {
+      for (const im of imageItems) { const b = Buffer.from(im.data, 'base64'); rec.outputBytes += b.length; h.update(b); }
+    } else { h.update(JSON.stringify(p)); }   // JSON.stringify blocks JSONL injection (newlines / control chars) (codex MEDIUM)
+    rec.contentHmac = h.digest('hex').slice(0, 32);
+    const day = rec.ts.slice(0, 10);
+    appendFileSync(join(AUDIT_DIR, `cu-${day}.jsonl`), JSON.stringify(rec) + '\n');
+  } catch {}
+}
+
+// OS-native backend (same as action-ext.mjs — a single source would be ideal, but it's duplicated since this is a PoC)
+const B = {
+  win32: {
+    probe:   ['pwsh', ['-NoProfile', '-File', join(dir, 'probe.ps1')]],
+    read:    ['pwsh', ['-NoProfile', '-File', join(dir, 'read-ui.ps1')]],
+    capture: ['pwsh', ['-NoProfile', '-File', join(dir, 'point-to-ask.ps1')]],
+  },
+  darwin: {
+    probe:   ['bash', [join(dir, 'mac', 'probe.sh')]],
+    read:    ['osascript', ['-l', 'JavaScript', join(dir, 'mac', 'read-ui.js')]],
+    capture: ['bash', [join(dir, 'mac', 'point-to-ask.sh')]],
+  },
+};
+
+// Returns: { payload, isError } — backend abnormal exit / non-JSON output is surfaced as isError (so an error never flows as if normal in the watch loop).
+function runBackend(kind, extraArgs = []) {
+  const b = B[plat]?.[kind];
+  if (!b) return { payload: { error: `unsupported platform/op: ${plat}/${kind}`, grade: 'P0 (manual) fallback' }, isError: true };
+  const [exe, base] = b;
+  const r = spawnSync(exe, [...base, ...extraArgs], { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 });
+  if (r.error) return { payload: { error: String(r.error) }, isError: true };
+  const failed = r.status !== 0;
+  try {
+    return { payload: JSON.parse(r.stdout), isError: failed };
+  } catch {
+    return { payload: { error: 'backend produced non-JSON output', exitCode: r.status, raw: (r.stdout || '').trim(), stderr: (r.stderr || '').trim() }, isError: true };
+  }
+}
+
+// Async backend runner for long/streaming ops (watch_capture). Never blocks the event loop, and a hard
+// timeout kills the child and returns isError — so one watch call can't hang the whole MCP server (codex #high).
+function runBackendAsync(kind, extraArgs = [], timeoutMs = 120000, cleanupDir = null) {
+  return new Promise((resolve) => {
+    const b = B[plat]?.[kind];
+    if (!b) return resolve({ payload: { error: `unsupported platform/op: ${plat}/${kind}`, grade: 'P0 (manual) fallback' }, isError: true });
+    const [exe, base] = b;
+    const MAX_OUT = 16 * 1024 * 1024;   // cap stdout/stderr accumulation; abort on overflow (codex #med DoS)
+    let out = '', err = '', settled = false, pending = null, killFallback = null;
+    const child = spawn(exe, [...base, ...extraArgs], { stdio: ['ignore', 'pipe', 'pipe'] });
+    const resolveOnce = (payload, isError, cleanupOwned = false) => {
+      if (settled) return; settled = true;
+      clearTimeout(timer); if (killFallback) clearTimeout(killFallback);
+      resolve({ payload, isError, cleanupOwned });
+    };
+    // Abort = decide the outcome + kill the child, but RESOLVE only after the child has CLOSED (file handles released)
+    // so the caller's reqDir cleanup can't race a still-flushing process (codex #high). If close never arrives within the
+    // grace window, resolve anyway but TAKE OWNERSHIP of reqDir cleanup (deferred to the eventual close, with a hard reaper)
+    // and signal cleanupOwned so the caller skips its own rmSync — we never delete a dir a live pwsh might still hold.
+    const abort = (payload) => {
+      if (pending || settled) return;
+      pending = payload;
+      try { child.kill(); } catch {}
+      killFallback = setTimeout(() => {
+        if (cleanupDir) {
+          child.once('close', () => { try { rmSync(cleanupDir, { recursive: true, force: true }); } catch {} });
+          const reaper = setTimeout(() => { try { rmSync(cleanupDir, { recursive: true, force: true }); } catch {} }, 30000);
+          if (reaper.unref) reaper.unref();
+        }
+        resolveOnce(pending, true, cleanupDir != null);
+      }, 3000);
+      if (killFallback.unref) killFallback.unref();
+    };
+    const timer = setTimeout(() => abort({ error: `watch timed out after ${timeoutMs}ms`, partial: (out || '').slice(0, 200) }), timeoutMs);
+    child.stdout.setEncoding('utf8'); child.stdout.on('data', (d) => { if (pending || settled) return; out += d; if (out.length > MAX_OUT) abort({ error: 'backend stdout exceeded cap' }); });
+    child.stderr.setEncoding('utf8'); child.stderr.on('data', (d) => { if (pending || settled || err.length >= MAX_OUT) return; err += d; });
+    child.on('error', (e) => resolveOnce({ error: String((e && e.message) || e) }, true));
+    child.on('close', (code) => {
+      if (pending) return resolveOnce(pending, true);   // aborted AND child closed within grace → caller can clean safely
+      if (settled) return;
+      try { resolveOnce(JSON.parse(out), code !== 0); }
+      catch { resolveOnce({ error: 'backend produced non-JSON output', exitCode: code, raw: (out || '').trim().slice(0, 500), stderr: (err || '').trim().slice(0, 500) }, true); }
+    });
+  });
+}
+
+// ── resident PowerShell worker (Windows MCP only) ─────────────────────────────
+// Removes the per-call pwsh re-spawn (~150-370ms setup) — keeps one worker alive and talks to it over JSON-lines.
+// Safeguards (codex cross-check): lazy start (spawn only on first call) · idle shutdown (N seconds with no command) ·
+//   single-worker command queue serialization · id matching · a generation (= process identity) guard to ignore stale events ·
+//   on crash, reject in-flight (no auto-retry of side-effect ops) · on no-response timeout, kill the worker and re-spawn.
+// Multi-instance: each MCP server has its own worker (dedicated pipe) -> no conflicts. On parent exit the
+//   worker auto-terminates via stdin EOF. watch isn't run on the worker (avoids long occupation) — done per-call.
+const WORKER = ['pwsh', ['-NoProfile', '-File', join(dir, 'worker.ps1')]];
+const WORKER_IDLE_MS = Number(process.env.VORTEX_AX_WORKER_IDLE_MS || 60000);
+const OP_TIMEOUT_MS = Number(process.env.VORTEX_AX_OP_TIMEOUT_MS || 10000);
+
+class WorkerManager {
+  constructor([exe, args]) { this.exe = exe; this.args = args; this.worker = null; this.buf = ''; this.seq = 0; this.inFlight = null; this.queue = []; this.idleTimer = null; }
+
+  call(op, args, timeoutMs = OP_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => { this.queue.push({ op, args, timeoutMs, resolve, reject }); this._pump(); });
+  }
+
+  _spawn() {
+    const child = spawn(this.exe, this.args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    this.worker = child; this.buf = '';
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      if (child !== this.worker) return;                 // generation guard: ignore the old worker
+      this.buf += chunk;
+      let nl;
+      while ((nl = this.buf.indexOf('\n')) >= 0) {
+        const line = this.buf.slice(0, nl).trim();
+        this.buf = this.buf.slice(nl + 1);
+        if (line) this._onLine(line);
+      }
+    });
+    child.stderr.on('data', (d) => process.stderr.write(`[ax-worker] ${d}`));
+    child.stdin.on('error', () => {});                   // EPIPE etc. are cleaned up in exit/error — here we only prevent an unhandled crash
+    child.on('error', (err) => this._onGone(child, `worker spawn/runtime error: ${err && err.message}`));
+    child.on('exit', (code) => this._onGone(child, `worker exited (code ${code}) before responding`));
+  }
+
+  _onGone(child, reason) {
+    if (child !== this.worker) return;                   // generation guard: ignore an old / already-replaced worker
+    this.worker = null;
+    const f = this.inFlight;
+    if (f) { clearTimeout(f.timer); this.inFlight = null; f.reject(new Error(reason)); }
+    if (this.queue.length) this._pump();                 // run the backlog on a new worker (no auto-retry of side-effect ops)
+  }
+
+  _onLine(line) {
+    let msg;
+    try { msg = JSON.parse(line); } catch { process.stderr.write(`[ax-worker] non-JSON line dropped: ${line.slice(0, 120)}\n`); return; }
+    const f = this.inFlight;
+    if (!f || msg.id !== f.id) return;                   // stale/mismatch
+    clearTimeout(f.timer); this.inFlight = null;
+    if (msg.ok) f.resolve(msg.result); else f.reject(new Error(msg.error || 'worker error'));
+    this._pump();
+  }
+
+  _pump() {
+    if (this.inFlight) return;
+    if (this.queue.length === 0) { this._scheduleIdle(); return; }
+    if (this.idleTimer) { clearTimeout(this.idleTimer); this.idleTimer = null; }
+    if (!this.worker) this._spawn();
+    const job = this.queue.shift();
+    const id = ++this.seq;
+    const timer = setTimeout(() => {
+      if (this.inFlight && this.inFlight.id === id) {     // no response -> assume the worker is stuck and kill it
+        const w = this.worker; this.worker = null;
+        const rej = this.inFlight.reject; this.inFlight = null;
+        if (w) { try { w.kill(); } catch {} }
+        rej(new Error(`worker op timeout after ${job.timeoutMs}ms`));
+        this._pump();
+      }
+    }, job.timeoutMs);
+    this.inFlight = { id, resolve: job.resolve, reject: job.reject, timer };
+    try { this.worker.stdin.write(JSON.stringify({ id, op: job.op, args: job.args }) + '\n'); }
+    catch (e) {
+      clearTimeout(timer); this.inFlight = null;
+      const w = this.worker; this.worker = null;
+      if (w) { try { w.kill(); } catch {} }
+      job.reject(e); this._pump();                        // assume the worker is dead, clean up, and proceed to the next request (prevents queue stall)
+    }
+  }
+
+  _scheduleIdle() {
+    if (this.idleTimer || !this.worker) return;
+    this.idleTimer = setTimeout(() => { this.idleTimer = null; if (!this.inFlight && this.queue.length === 0) this.dispose(); }, WORKER_IDLE_MS);
+    if (this.idleTimer.unref) this.idleTimer.unref();
+  }
+
+  dispose() {
+    if (this.idleTimer) { clearTimeout(this.idleTimer); this.idleTimer = null; }
+    const w = this.worker; this.worker = null;
+    if (w) { try { w.stdin.end(); } catch {} try { w.kill(); } catch {} }
+  }
+}
+
+const workerMgr = new WorkerManager(WORKER);
+
+// watchIds this server process has dispatched a poll_change for — to detect a SILENT baseline reset
+// (the resident worker was idle-disposed / killed / crashed and lost its in-memory watch state). codex #high.
+const pollSeen = new Set();
+
+// Server-owned volatility (codex blocker, design §8): when a backend wrote screenshot file(s), read them inline as
+// MCP image content and DELETE them immediately — no on-disk path is returned, so a crashed/idle caller can't leave
+// sensitive screenshots behind. Bounded: at most MAX_INLINE_IMAGES are embedded; extras are still unlinked + counted.
+const MAX_INLINE_IMAGES = 8;
+const MAX_IMAGE_BYTES = 8 * 1024 * 1024;          // per-image cap (codex #med — bound response size, avoid blocking read)
+const MAX_TOTAL_INLINE_BYTES = 24 * 1024 * 1024;  // total inline cap across a response
+function materializeImages(payload) {
+  const images = [];
+  let inlined = 0, dropped = 0, totalBytes = 0;
+  const take = (p) => {
+    if (!p || typeof p !== 'string') return false;
+    let ok = false;
+    try {
+      const sz = statSync(p).size;
+      if (inlined < MAX_INLINE_IMAGES && sz <= MAX_IMAGE_BYTES && totalBytes + sz <= MAX_TOTAL_INLINE_BYTES) {
+        images.push({ type: 'image', data: readFileSync(p).toString('base64'), mimeType: 'image/png' });
+        inlined++; totalBytes += sz; ok = true;
+      } else { dropped++; }
+    } catch { /* file already gone — fine */ }
+    try { unlinkSync(p); } catch {}
+    return ok;
+  };
+  if (payload && typeof payload === 'object') {
+    if (payload.path) { const g = take(payload.path); delete payload.path; payload.image = g ? 'inline' : 'unavailable'; }
+    if (Array.isArray(payload.captures)) {
+      for (const f of payload.captures) { if (f && f.path) { const g = take(f.path); delete f.path; f.image = g ? 'inline' : 'unavailable'; } }
+    }
+    if (dropped > 0) payload.imagesDropped = dropped;
+  }
+  return images;
+}
+
+async function viaWorker(op, args, timeoutMs) {
+  try { return { payload: await workerMgr.call(op, args, timeoutMs), isError: false }; }
+  catch (e) { return { payload: { error: String((e && e.message) || e) }, isError: true }; }
+}
+
+const TOOLS = [
+  {
+    name: 'probe',
+    description: 'Check whether screen perception works in this environment + measure display/capture latency (P0.5).',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'read_ui',
+    description: 'Structured perception of the active/targeted window — UIA(Win)/AX(mac) tree: elements, roles, coordinates, text. Zero images, ~0 tokens (P1 primary).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        window: { type: 'string', description: 'Target by a substring of the window title. If omitted, foreground.' },
+        target: { type: 'string', enum: ['foreground', 'cursor'], description: 'Target to use when no window is given.' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'capture_screen',
+    description: 'Pixel capture — fallback for canvas/games that structured perception cannot read. Target (priority): region > window > monitor > (default) around the cursor. Returns a PNG path (volatility is the caller\'s job, §8).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        boxW: { type: 'number', description: 'Cursor-mode box width (default 600).' },
+        boxH: { type: 'number', description: 'Cursor-mode box height (default 400).' },
+        region: {
+          type: 'object',
+          description: 'Capture a fixed region (ignores cursor). Virtual-screen physical coordinates.',
+          properties: { x: { type: 'number' }, y: { type: 'number' }, w: { type: 'number' }, h: { type: 'number' } },
+          required: ['x', 'y', 'w', 'h'],
+          additionalProperties: false,
+        },
+        window: { type: 'string', description: 'Window title substring -> capture that window\'s region (ignores cursor). Tracks the window even as it moves.' },
+        monitor: { type: 'string', description: "Target a monitor (ignores cursor): 1-based index ('3') or 'primary'. For continuously watching a game-only monitor." },
+        detail: { type: 'string', description: "Resolution preset: 'gist' (flow only, small) / 'normal' (default) / 'text' (text/code, large). For reading text, prefer region/window + 'text' over a whole monitor." },
+        scale: { type: 'number', description: 'Upscale factor (small regions). When set, overrides detail.' },
+        maxSide: { type: 'number', description: 'Upper bound on the output longest side in px. When set, overrides detail.' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'watch_capture',
+    description: 'Capture a fixed target N times at a set interval (within one pwsh process — avoids per-frame re-spawn cost). With changeOnly, save only frames that changed from the previous one. Synchronous/blocking (waits for the response over frames×interval) — Windows-only PoC. Target priority: region > window > monitor > cursor.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        frames: { type: 'number', description: 'Number of frames to capture (>1).' },
+        intervalMs: { type: 'number', description: 'Interval between frames (ms, default 1000).' },
+        changeOnly: { type: 'boolean', description: 'Save only frames that changed from the previous one (default false).' },
+        changeThreshold: { type: 'number', description: 'Change-detection threshold % (default 2.0).' },
+        region: {
+          type: 'object',
+          description: 'Fixed region (ignores cursor). Virtual-screen physical coordinates.',
+          properties: { x: { type: 'number' }, y: { type: 'number' }, w: { type: 'number' }, h: { type: 'number' } },
+          required: ['x', 'y', 'w', 'h'],
+          additionalProperties: false,
+        },
+        window: { type: 'string', description: 'Window title substring (ignores cursor, tracks movement).' },
+        monitor: { type: 'string', description: "Target a monitor (ignores cursor): index or 'primary'." },
+        boxW: { type: 'number', description: 'Cursor-mode box width.' },
+        boxH: { type: 'number', description: 'Cursor-mode box height.' },
+        detail: { type: 'string', description: "Resolution preset: 'gist'/'normal'/'text'. An explicit scale/maxSide takes precedence." },
+        scale: { type: 'number', description: 'Upscale factor. When set, overrides detail.' },
+        maxSide: { type: 'number', description: 'Upper bound on the output longest side in px. When set, overrides detail.' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'poll_change',
+    description: 'Look at the screen once (async watch primitive) — capture the target once, compare with the previous shot, and immediately return only the change rate. The resident worker remembers the previous state per watchId (continuity). **By default, metadata only (changed, changePct; no image saved = token savings)** — pass includeImage:true to also get the image (path) only when you actually need to see the screen. "Watching alongside" is built by the agent repeatedly calling this tool (polling) every 1-2 seconds — non-blocking, the user can step in at any time. Use reset:true on start / target change. Windows-only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        region: {
+          type: 'object',
+          description: 'Fixed region (ignores cursor). Virtual-screen physical coordinates.',
+          properties: { x: { type: 'number' }, y: { type: 'number' }, w: { type: 'number' }, h: { type: 'number' } },
+          required: ['x', 'y', 'w', 'h'],
+          additionalProperties: false,
+        },
+        window: { type: 'string', description: 'Window title substring (ignores cursor, tracks movement).' },
+        monitor: { type: 'string', description: "Target a monitor (ignores cursor): index or 'primary'." },
+        boxW: { type: 'number', description: 'Cursor-mode box width.' },
+        boxH: { type: 'number', description: 'Cursor-mode box height.' },
+        scale: { type: 'number', description: 'Upscale factor when includeImage. When set, overrides detail.' },
+        maxSide: { type: 'number', description: 'Upper bound on the output longest side in px when includeImage. When set, overrides detail.' },
+        changeThreshold: { type: 'number', description: 'Change-detection threshold % (default 2).' },
+        watchId: { type: 'string', description: 'Watch-session id (default "default"). The previous state is remembered under this id.' },
+        reset: { type: 'boolean', description: 'If true, discard the previous state and start a new baseline (on watch start / target change).' },
+        detail: { type: 'string', description: "Resolution preset: 'gist'/'normal'/'text' (the saved image size when includeImage)." },
+        includeImage: { type: 'boolean', description: 'Default false = metadata only (changePct etc., token savings). If true, also save and return the changed/baseline frame as a PNG (path).' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'beep',
+    description: 'Sound alert — call this to emit a beep when you have a message to show the user during watching (so they notice while looking at a game / another screen). Recommended to call right before printing the message. Windows-only. (A precursor to future voice TTS.)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        pattern: { type: 'string', description: "Beep pattern: 'info' (once) / 'warn' (twice) / 'urgent' (three times). Default info." },
+        count: { type: 'number', description: 'Repeat count (overrides pattern when set). 1-10.' },
+        frequency: { type: 'number', description: 'Pitch in Hz (37-32767).' },
+        durationMs: { type: 'number', description: 'Duration of one beep in ms.' },
+      },
+      additionalProperties: false,
+    },
+  },
+];
+
+const server = new Server({ name: 'computer-use', version: '0.0.1-poc' }, { capabilities: { tools: {} } });
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: a = {} } = req.params;
+  const useWorker = plat === 'win32';   // the resident worker is Windows PowerShell backend only
+  let result;
+  let reqDir = null;   // per-request temp dir for screenshots — deleted in finally on EVERY exit path (codex blocker: timeout/error left files behind)
+  // Clamp output-size knobs at the MCP boundary so a huge upscale can't blow up the response / PS render (codex #med).
+  if (a.scale != null) { const s = Number(a.scale); a.scale = Number.isFinite(s) ? Math.min(8, Math.max(0.1, s)) : undefined; }
+  if (a.maxSide != null) { const m = Number(a.maxSide); a.maxSide = Number.isFinite(m) ? Math.min(4096, Math.max(16, Math.floor(m))) : undefined; }
+  try {
+  if (name === 'probe') {
+    result = useWorker ? await viaWorker('probe', {}) : runBackend('probe');
+  } else if (name === 'read_ui') {
+    if (useWorker) {
+      const wa = {};
+      if (a.window) wa.windowMatch = String(a.window);
+      if (a.target) wa.target = String(a.target);
+      result = await viaWorker('read_ui', wa);
+    } else {
+      const args = [];
+      if (a.window) args.push('-WindowMatch', String(a.window));
+      if (a.target) args.push('-Target', String(a.target));
+      result = runBackend('read', args);
+    }
+  } else if (name === 'capture_screen') {
+    reqDir = mkdtempSync(join(tmpdir(), 'vortex-cu-'));
+    if (useWorker) {
+      const wa = { outDir: reqDir };
+      if (a.region) wa.region = `${a.region.x},${a.region.y},${a.region.w},${a.region.h}`;
+      if (a.window) wa.windowMatch = String(a.window);
+      if (a.monitor != null) wa.monitor = String(a.monitor);
+      if (a.boxW) wa.boxW = a.boxW;
+      if (a.boxH) wa.boxH = a.boxH;
+      if (a.detail) wa.detail = String(a.detail);
+      if (a.scale != null) wa.scale = a.scale;
+      if (a.maxSide != null) wa.maxSide = a.maxSide;
+      result = await viaWorker('capture', wa);
+    } else {
+      const args = ['-OutDir', reqDir];
+      if (a.boxW) args.push('-BoxW', String(a.boxW));
+      if (a.boxH) args.push('-BoxH', String(a.boxH));
+      result = runBackend('capture', args);
+    }
+  } else if (name === 'watch_capture') {
+    // watch isn't run on the resident worker (avoids blocking other calls with a long occupation, codex #1) -> always per-call spawn.
+    if (plat !== 'win32') {
+      result = { payload: { error: 'watch_capture is currently Windows-only', platform: plat }, isError: true };
+    } else {
+      // Hard caps so one watch call can't run unbounded; async runner so it never blocks the server (codex #high).
+      reqDir = mkdtempSync(join(tmpdir(), 'vortex-cu-'));
+      const MAX_FRAMES = 60, MIN_INTERVAL = 100, MAX_INTERVAL = 10000, MAX_WATCH_MS = 180000;
+      const reqFrames = Number(a.frames), reqInterval = Number(a.intervalMs);
+      const frames = Math.min(MAX_FRAMES, Math.max(1, Number.isFinite(reqFrames) && reqFrames > 0 ? Math.floor(reqFrames) : 2));
+      const intervalMs = Math.min(MAX_INTERVAL, Math.max(MIN_INTERVAL, Number.isFinite(reqInterval) && reqInterval > 0 ? Math.floor(reqInterval) : 1000));
+      const args = ['-WatchFrames', String(frames), '-IntervalMs', String(intervalMs), '-OutDir', reqDir];
+      if (a.changeOnly) args.push('-ChangeOnly');
+      if (a.changeThreshold != null) args.push('-ChangeThreshold', String(a.changeThreshold));
+      if (a.region) args.push('-Region', `${a.region.x},${a.region.y},${a.region.w},${a.region.h}`);
+      if (a.window) args.push('-WindowMatch', String(a.window));
+      if (a.monitor != null) args.push('-Monitor', String(a.monitor));
+      if (a.boxW) args.push('-BoxW', String(a.boxW));
+      if (a.boxH) args.push('-BoxH', String(a.boxH));
+      if (a.detail) args.push('-Detail', String(a.detail));
+      if (a.scale != null) args.push('-Scale', String(a.scale));
+      if (a.maxSide != null) args.push('-MaxSide', String(a.maxSide));
+      const timeoutMs = Math.min(MAX_WATCH_MS, frames * intervalMs + 15000);
+      result = await runBackendAsync('capture', args, timeoutMs, reqDir);
+      if (result.cleanupOwned) reqDir = null;   // runBackendAsync deferred cleanup (timeout/cap fallback) — don't race it in finally
+    }
+  } else if (name === 'poll_change') {
+    // async watch primitive — a fast single shot, so it goes through the worker (which also holds the previous state). win32 only.
+    if (plat !== 'win32') {
+      result = { payload: { error: 'poll_change is currently Windows-only', platform: plat }, isError: true };
+    } else {
+      const wa = {};
+      if (a.includeImage) { reqDir = mkdtempSync(join(tmpdir(), 'vortex-cu-')); wa.outDir = reqDir; wa.includeImage = true; }
+      if (a.region) wa.region = `${a.region.x},${a.region.y},${a.region.w},${a.region.h}`;
+      if (a.window) wa.windowMatch = String(a.window);
+      if (a.monitor != null) wa.monitor = String(a.monitor);
+      if (a.boxW) wa.boxW = a.boxW;
+      if (a.boxH) wa.boxH = a.boxH;
+      if (a.scale != null) wa.scale = a.scale;
+      if (a.maxSide != null) wa.maxSide = a.maxSide;
+      if (a.detail) wa.detail = String(a.detail);
+      if (a.changeThreshold != null) wa.changeThreshold = a.changeThreshold;
+      const wid = a.watchId ? String(a.watchId) : 'default';
+      if (a.watchId) wa.watchId = wid;
+      if (a.reset) wa.reset = true;
+      const seenBefore = pollSeen.has(wid);
+      result = await viaWorker('poll_change', wa);
+      // Record the watchId only after a SUCCESSFUL poll (payload carries a boolean baseline) — a failed first call must
+      // not make the next valid baseline look like a reset; bound the set so attacker-chosen watchIds can't grow it forever. codex #low.
+      if (result && result.payload && typeof result.payload.baseline === 'boolean') {
+        if (pollSeen.size > 1000) pollSeen.clear();
+        pollSeen.add(wid);
+      }
+      // A non-reset follow-up that comes back baseline=true means the worker lost its state (restart/idle-dispose/crash).
+      // Surface it as a reset so the agent treats it as a fresh baseline — NOT as "no change" (a real change in the gap would otherwise be silently missed). codex #high.
+      if (!a.reset && seenBefore && result && result.payload && result.payload.baseline === true) {
+        result.payload.stateReset = true;
+        result.payload.warning = 'watch state was lost (worker restarted/idle-disposed) — this is a fresh baseline, not a "no change" result; a change during the gap may have been missed.';
+      }
+    }
+  } else if (name === 'beep') {
+    if (plat !== 'win32') {
+      result = { payload: { error: 'beep is currently Windows-only', platform: plat }, isError: true };
+    } else {
+      const wa = {};
+      if (a.pattern) wa.pattern = String(a.pattern);
+      if (a.count != null) wa.count = a.count;
+      if (a.frequency != null) wa.frequency = a.frequency;
+      if (a.durationMs != null) wa.durationMs = a.durationMs;
+      result = await viaWorker('beep', wa);
+    }
+  } else {
+    return { content: [{ type: 'text', text: `unknown tool: ${name}` }], isError: true };
+  }
+  const imageItems = materializeImages(result.payload);
+  auditLog(name, result.payload, imageItems);   // metadata/HMAC only — original image and text are not stored (§8)
+  return { content: [{ type: 'text', text: JSON.stringify(result.payload, null, 2) }, ...imageItems], isError: result.isError };
+  } finally {
+    if (reqDir) { try { rmSync(reqDir, { recursive: true, force: true }); } catch {} }
+  }
+});
+
+// Clean up the worker on server shutdown (it would also auto-terminate via stdin EOF when the parent dies, but do it explicitly).
+process.on('exit', () => workerMgr.dispose());
+process.on('SIGINT', () => process.exit(0));
+process.on('SIGTERM', () => process.exit(0));
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+process.stderr.write(`[computer-use MCP] ready on stdio (worker=${plat === 'win32' ? 'on' : 'off'}; tools: probe, read_ui, capture_screen, watch_capture, poll_change, beep)\n`);

package/scripts/point-to-ask.ps1

@@ -0,0 +1,28 @@
+# computer-use — point-to-ask / capture (throwaway PoC) — CLI adapter over the shared logic in lib.ps1.
+# Target (priority): Region > WindowMatch > Monitor > (default) cursor. Includes watch (-WatchFrames>1). Logic lives in lib.ps1::Invoke-AxCapture.
+param(
+  [int]$BoxW = 600,
+  [int]$BoxH = 400,
+  [double]$Scale = 0,
+  [int]$MaxSide = 0,
+  [long]$MaxPixels = 40000000,
+  [string]$Detail = 'normal',
+  [string]$Region = '',
+  [string]$WindowMatch = '',
+  [string]$Monitor = '',
+  [int]$WatchFrames = 1,
+  [int]$IntervalMs = 1000,
+  [switch]$ChangeOnly,
+  [double]$ChangeThreshold = 2.0,
+  [string]$OutDir = (Join-Path $env:TEMP 'vortex-ax-poc')
+)
+$ErrorActionPreference = 'Stop'
+. (Join-Path $PSScriptRoot 'lib.ps1')
+Initialize-AxEnv
+$params = @{
+  BoxW = $BoxW; BoxH = $BoxH; Scale = $Scale; MaxSide = $MaxSide; MaxPixels = $MaxPixels; Detail = $Detail
+  Region = $Region; WindowMatch = $WindowMatch; Monitor = $Monitor
+  WatchFrames = $WatchFrames; IntervalMs = $IntervalMs; ChangeThreshold = $ChangeThreshold; OutDir = $OutDir
+}
+if ($ChangeOnly) { $params.ChangeOnly = $true }
+Invoke-AxCapture @params | ConvertTo-Json -Depth 6

package/scripts/probe.ps1

@@ -0,0 +1,6 @@
+# computer-use — P0.5 probe (throwaway PoC) — CLI adapter over the shared logic in lib.ps1.
+# Output = a single JSON blob. Logic lives in lib.ps1::Get-AxProbe.
+$ErrorActionPreference = 'Stop'
+. (Join-Path $PSScriptRoot 'lib.ps1')
+Initialize-AxEnv
+Get-AxProbe | ConvertTo-Json -Depth 6

package/scripts/read-ui.ps1

@@ -0,0 +1,13 @@
+# computer-use — P1 read_ui (throwaway PoC) — CLI adapter over the shared logic in lib.ps1.
+# Active/targeted window UIA tree (elements, roles, coordinates, id) + TextPattern body text -> JSON, zero images. Logic lives in lib.ps1::Get-AxReadUi.
+param(
+  [int]$MaxDepth = 5,
+  [int]$MaxElements = 70,
+  [int]$TextCap = 1500,
+  [ValidateSet('foreground','cursor')] [string]$Target = 'foreground',
+  [string]$WindowMatch = ''
+)
+$ErrorActionPreference = 'Stop'
+. (Join-Path $PSScriptRoot 'lib.ps1')
+Initialize-AxEnv
+Get-AxReadUi -MaxDepth $MaxDepth -MaxElements $MaxElements -TextCap $TextCap -Target $Target -WindowMatch $WindowMatch | ConvertTo-Json -Depth 12