@optimuslabs/harness-map-staging 1.5.40 → 1.5.41

package/dist/agent_access/launchd_job.js

@@ -0,0 +1,105 @@
+/**
+ * Runs the blocked-agent window process as a one-off launchd job in the user's GUI session
+ * (docs/agent-exception-requests/DESIGN.md), instead of as a child of the hook.
+ *
+ * A child of the hook lives in the agent's process tree and context: an agent that stops what its
+ * hook started once the hook returns, or runs hooks where no window can open (seen with old Cursor
+ * versions), left the user with no pop-up at all. launchd starts the job itself, in the session the
+ * Dock and Finder run in, so neither can reach it. The job runs once (no KeepAlive), from a plist in
+ * a folder of its own (mode 600); the window process removes the job when it is done, and jobs a
+ * crashed process left behind are removed the next time one starts. Nothing here needs root.
+ */
+import { spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+const LABEL_PREFIX = 'io.optimuslabs.agent-window.';
+/** A label this module made, and nothing else: the prefix and 12 hex characters. */
+const OUR_LABEL = /^io\.optimuslabs\.agent-window\.[0-9a-f]{12}$/;
+/** The user's GUI launchd domain, and nothing else. */
+const GUI_DOMAIN = /^gui\/\d+$/;
+/** The env names the window process needs (story id, endpoint, home, temp folder): nothing else. */
+const PASSED_ENV = /^(OPTIMUS_[A-Z0-9_]+|HOME|USER|PATH|TMPDIR|LANG)$/;
+/** Set on the job, so the window process knows its label and plist folder. */
+export const JOB_LABEL_ENV = 'OPTIMUS_WINDOW_JOB';
+const JOB_DIR_ENV = 'OPTIMUS_WINDOW_JOB_DIR';
+function xml(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+/** The job's plist: run `program` once, now, with `env`. */
+export function jobPlist(label, program, env) {
+    const args = program.map((a) => `<string>${xml(a)}</string>`).join('');
+    const vars = Object.entries(env)
+        .map(([k, v]) => `<key>${xml(k)}</key><string>${xml(v)}</string>`)
+        .join('');
+    return ('<?xml version="1.0" encoding="UTF-8"?>\n' +
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n' +
+        `<plist version="1.0"><dict><key>Label</key><string>${xml(label)}</string>` +
+        `<key>ProgramArguments</key><array>${args}</array>` +
+        `<key>EnvironmentVariables</key><dict>${vars}</dict>` +
+        '<key>RunAtLoad</key><true/><key>KeepAlive</key><false/></dict></plist>\n');
+}
+/** The env the job gets: what the window process needs from this one, and its own job details. */
+function jobEnv(label, dir) {
+    const env = {};
+    for (const [k, v] of Object.entries(process.env))
+        if (PASSED_ENV.test(k) && v !== undefined)
+            env[k] = v;
+    env.TMPDIR = tmpdir();
+    env[JOB_LABEL_ENV] = label;
+    env[JOB_DIR_ENV] = dir;
+    return env;
+}
+function guiDomain() {
+    return typeof process.getuid === 'function' ? `gui/${process.getuid()}` : null;
+}
+/** Remove one of our jobs from the domain; anything that is not exactly ours is left alone. */
+function bootout(domain, label) {
+    if (!GUI_DOMAIN.test(domain) || !OUR_LABEL.test(label))
+        return;
+    const target = `${domain}/${label}`;
+    // A fixed command, no shell, and a target checked above to be our own job in the user's domain.
+    spawnSync('launchctl', ['bootout', target]); // nosafe: SAFE801
+}
+/** Remove the window jobs no process runs any more (one a crashed window process left behind). */
+function sweepFinishedJobs(domain) {
+    const out = spawnSync('launchctl', ['list'], { encoding: 'utf8' });
+    for (const line of (out.stdout || '').split('\n')) {
+        const [pid, , label] = line.trim().split(/\s+/);
+        if (pid === '-' && label)
+            bootout(domain, label);
+    }
+}
+/**
+ * Start `program` as a one-off launchd job in the user's GUI session; the job's label, or null when
+ * launchd would not take it (the caller then starts the process itself).
+ */
+export function startLaunchdJob(program) {
+    const domain = guiDomain();
+    if (!domain)
+        return null;
+    const dir = mkdtempSync(join(tmpdir(), 'optimus-window-job-'));
+    const label = `${LABEL_PREFIX}${randomBytes(6).toString('hex')}`;
+    const plist = join(dir, `${label}.plist`);
+    writeFileSync(plist, jobPlist(label, program, jobEnv(label, dir)), { mode: 0o600 });
+    sweepFinishedJobs(domain);
+    // A fixed command, no shell; the plist is one this process just wrote in its own folder.
+    const out = spawnSync('launchctl', ['bootstrap', domain, plist], { encoding: 'utf8' }); // nosafe: SAFE801
+    if (out.status === 0)
+        return label;
+    rmSync(dir, { recursive: true, force: true });
+    throw new Error(`launchctl bootstrap failed (exit ${out.status}): ${(out.stderr || '').trim()}`);
+}
+/** In the window process: remove its own job and plist folder, if launchd started it. */
+export function endLaunchdJob() {
+    const label = process.env[JOB_LABEL_ENV] || '';
+    const dir = process.env[JOB_DIR_ENV] || '';
+    const domain = guiDomain();
+    if (dir && basename(dir).startsWith('optimus-window-job-') && dirname(dir) === tmpdir()) {
+        rmSync(dir, { recursive: true, force: true });
+    }
+    // Last: removing the job ends this process.
+    if (domain)
+        bootout(domain, label);
+}

package/dist/agent_access/window_runner.js

@@ -2,24 +2,30 @@
  * Shows the blocked-agent window (docs/agent-exception-requests/DESIGN.md).
  *
  * Started detached by the prompt gate (`launchAgentAccessWindow`), so the hook returns its block at
- * once. Run as `node window_runner.js <agent> [<words.json>]`: an agent's own block reads the window's
+ * once. Run as `node window_runner.js <agent> <kind> [<words.json>]`: an agent's own block reads the window's
  * words from the synced approvals; a tenant or email-domain block passes them, built by the gate, in
  * a file of its own temporary folder. It draws the window with `osascript` (macOS only),
  * then acts on what the user chose: Open launches the approved app, Cancel only closes it. The prompt
- * was already blocked. Nothing here talks to the network; a failure is logged and never thrown.
+ * was already blocked. Whether the window was shown, or why not (the `osascript` error), is reported
+ * into the prompt's story as a `compliance/agent_access_window` functional run, so a machine where `osascript`
+ * cannot draw it is visible on the server; the gate had already told the hook the window was up, so
+ * the user saw no pop-up at all. Nothing is ever thrown.
  */
 import { spawn, spawnSync } from 'node:child_process';
 import { mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { release, tmpdir } from 'node:os';
 import { basename, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { reportFunctionalRun } from '../log_config_files/runtime/client_event_reporter.js';
 import { hookRunLog } from '../log_config_files/runtime/hook_logger.js';
 import { readRemediationInstructionsFile } from '../log_config_files/runtime/management_storage.js';
 import { approvalId } from './decision.js';
+import { endLaunchdJob, JOB_LABEL_ENV, startLaunchdJob } from './launchd_job.js';
 const HERE = dirname(fileURLToPath(import.meta.url));
 const WINDOW_SCRIPT = join(HERE, '..', 'agent_block_window', 'agent_block_window.jxa');
 /** The agents the gate checks, by approval id: nothing else is ever passed to a process. */
 const AGENTS = ['claude', 'cursor', 'codex', 'copilot', 'opencode'];
+const KINDS = ['agent', 'login', 'skill'];
 /** A macOS bundle identifier, and nothing that could be read as an option or a path. */
 const BUNDLE_ID = /^[A-Za-z0-9][A-Za-z0-9.-]{0,254}$/;
 /** Where the gate leaves a login block's words for the runner: a folder of its own under tmpdir. */
@@ -56,18 +62,23 @@ function syncedWindow(agent) {
     return readRemediationInstructionsFile().agent_access_windows?.[approvalId(agent)];
 }
 /**
- * Start the runner in the background, detached from the hook, on macOS only; true when it started.
- * `words` are a tenant or email-domain block's, built by the gate; without them the runner reads the
- * agent's own block window from the synced approvals. False when there is nothing to show (an
- * approvals file synced before the window existed), so Cursor's hook keeps its own alert.
+ * Start the runner in the background, on macOS only; true when it started. `words` are a tenant or
+ * email-domain block's, built by the gate; without them the runner reads the agent's own block
+ * window from the synced approvals. False when there is nothing to show (an approvals file synced
+ * before the window existed), so Cursor's hook keeps its own alert.
+ *
+ * launchd starts it in the user's GUI session (`launchd_job.ts`), out of reach of what the agent
+ * does to its hook's processes; when launchd will not take the job, it is started here, detached.
  */
-export function launchAgentAccessWindow(agent, words) {
-    if (process.platform !== 'darwin' || !AGENTS.includes(agent))
+export function launchAgentAccessWindow(agent, kind, words) {
+    if (process.platform !== 'darwin' || !AGENTS.includes(agent) || !KINDS.includes(kind))
         return false;
     if (!words && !syncedWindow(agent))
         return false;
     try {
-        const args = [fileURLToPath(import.meta.url), agent, ...(words ? [writeWords(words)] : [])];
+        const args = [fileURLToPath(import.meta.url), agent, kind, ...(words ? [writeWords(words)] : [])];
+        if (startByLaunchd([process.execPath, ...args]))
+            return true;
         const options = { detached: true, stdio: 'ignore' };
         // An argument list, no shell: an agent from the fixed list above, and the path of a file it wrote.
         const child = spawn(process.execPath, args, options); // nosafe: SAFE801
@@ -79,24 +90,48 @@ export function launchAgentAccessWindow(agent, words) {
         return false;
     }
 }
+/** Start the runner as a launchd job; false (logged) when launchd would not take it. */
+function startByLaunchd(program) {
+    try {
+        return startLaunchdJob(program) !== null;
+    }
+    catch (err) {
+        hookRunLog(`agent_access_window: launchd: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}
+/** The installed Cursor's version ('' for another agent or when it cannot be read). */
+function agentVersion(agent) {
+    if (agent !== 'cursor')
+        return '';
+    const plist = '/Applications/Cursor.app/Contents/Info.plist';
+    const out = spawnSync('plutil', ['-extract', 'CFBundleShortVersionString', 'raw', plist], { encoding: 'utf8' });
+    return out.status === 0 ? (out.stdout || '').trim().slice(0, 32) : '';
+}
 /** Draw the window and return what the user did; null when it could not open. */
 export function showWindow(words) {
+    return drawWindow(words).result;
+}
+/** Draw the window: what the user did, or why it could not be shown (`error`, '' when it was). */
+export function drawWindow(words) {
     if (!words)
-        return null;
+        return { result: null, error: 'no words to show' };
     const dir = mkdtempSync(join(tmpdir(), 'optimus-window-'));
     const payloadPath = join(dir, 'payload.json');
     try {
         writeFileSync(payloadPath, JSON.stringify({ words }));
         const out = spawnSync('osascript', ['-l', 'JavaScript', WINDOW_SCRIPT, payloadPath], { encoding: 'utf8' });
         if (out.status !== 0) {
-            hookRunLog(`agent_access_window: osascript failed: ${(out.stderr || '').trim()}`);
-            return null;
+            const error = `osascript failed (exit ${out.status ?? out.signal}): ${(out.stderr || out.error?.message || '').trim()}`;
+            hookRunLog(`agent_access_window: ${error}`);
+            return { result: null, error };
         }
-        return JSON.parse(out.stdout.trim());
+        return { result: JSON.parse(out.stdout.trim()), error: '' };
     }
     catch (err) {
-        hookRunLog(`agent_access_window: ${err instanceof Error ? err.message : String(err)}`);
-        return null;
+        const error = err instanceof Error ? err.message : String(err);
+        hookRunLog(`agent_access_window: ${error}`);
+        return { result: null, error };
     }
     finally {
         rmSync(dir, { recursive: true, force: true });
@@ -115,15 +150,33 @@ export function actOn(result) {
     if (result.action === 'open')
         openApp(result.bundle_id ?? '');
 }
-export function runAgentAccessWindow(agent, wordsPath = '') {
+/**
+ * Show the window, act on the choice, and report into the prompt's story whether it was shown
+ * (the runner inherits the gate's story id). Awaited, so the report is sent before the runner exits.
+ */
+export async function runAgentAccessWindow(agent, kind, wordsPath = '') {
+    const launched = process.env[JOB_LABEL_ENV] ? 'launchd' : 'spawn';
+    const metadata = { darwin: release(), kind, launched, agent_version: agentVersion(agent) };
+    // The server knows a fixed set of units; the window is part of the prompt gate's compliance.
+    // "started" first: a window process the agent stopped never reports more, and that shows.
+    const report = { unit: 'compliance', command: 'agent_access_window', metadata };
+    await reportFunctionalRun({ ...report, outcome: 'started', message: `${agent}: window process started (${launched})` });
     const words = wordsPath ? readWords(wordsPath) : syncedWindow(agent);
-    const result = showWindow(words ?? undefined);
+    const { result, error } = drawWindow(words ?? undefined);
     if (result)
         actOn(result);
+    await reportFunctionalRun({
+        ...report,
+        outcome: result ? 'ok' : 'failed',
+        message: (result ? `${agent}: shown, closed with ${result.action}` : `${agent}: not shown: ${error}`).slice(0, 500),
+        detail: error,
+    });
+    endLaunchdJob();
 }
 const isEntryPoint = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
 if (isEntryPoint) {
-    const [agent, wordsPath] = process.argv.slice(2);
-    if (agent && AGENTS.includes(agent))
-        runAgentAccessWindow(agent, wordsPath);
+    const [agent, kind, wordsPath] = process.argv.slice(2);
+    if (agent && AGENTS.includes(agent) && KINDS.includes(kind)) {
+        void runAgentAccessWindow(agent, kind, wordsPath);
+    }
 }

package/dist/compliance_prompt_gate.js

@@ -334,7 +334,8 @@ function blockedByLogin(agent, ide) {
     // The blocked-agent window opens beside every block, in the background, so the hook answers at
     // once: an agent's own from the synced approvals, a login's from the words built here. Where it
     // could not start, Cursor's hook keeps its alert.
-    const windowShown = launchAgentAccessWindow(approvalId(agent), block.window);
+    // A login block (tenant, email domain) brings its own words; the agent's own comes from the sync.
+    const windowShown = launchAgentAccessWindow(approvalId(agent), block.window ? 'login' : 'agent', block.window);
     console.log(agent === 'codex' ? codexBlockPayload(block.reason) : blockPayload(ide, block.reason, windowShown));
     return true;
 }

package/dist/log_config_files/runtime/skill_block_sessions.js

@@ -175,7 +175,7 @@ function openWindowOf(uuid) {
     if (!words)
         return false;
     windowsShown.add(uuid);
-    return launchAgentAccessWindow('claude', words);
+    return launchAgentAccessWindow('claude', 'skill', words);
 }
 /** Open the window beside the block of the skill named `skill` (a stopped session, a typed command). */
 export function openSkillBlockWindow(skill) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optimuslabs/harness-map-staging",
-  "version": "1.5.40",
+  "version": "1.5.41",
   "description": "CLI helpers for logging hardware UUIDs and posting startup payloads to Optimus Security.",
   "type": "module",
   "bin": {