mecord-connect 1.0.0

package/runtime/app/src/capabilities/windows-uia.js

@@ -0,0 +1,331 @@
+import crypto from 'node:crypto';
+import { spawn,                                     } from 'node:child_process';
+import path from 'node:path';
+import readline from 'node:readline';
+                                                                                                                                     
+import { evidence } from '../core/evidence.js';
+import { OperatorError } from '../core/errors.js';
+import { safeChildEnvironment } from '../core/child-environment.js';
+
+const SCORE                  = {
+  reliability: 0.95,
+  latency: 0.91,
+  determinism: 0.98,
+  security: 0.97,
+  reversibility: 0.88,
+  informationQuality: 0.98,
+  interactionCost: 0.01
+};
+
+const MAX_RESPONSE_LINE_BYTES = 4 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 20_000;
+const MAX_OBSERVE_MS = 5_000;
+const MAX_WAIT_MS = 10_000;
+const DEFAULT_MAX_WINDOWS = 50;
+const MAX_WINDOWS = 200;
+const UIA_OPERATIONS = ['invoke', 'set_value', 'focus', 'select', 'expand', 'collapse', 'scroll', 'activate_window']         ;
+const SCROLL_AMOUNTS = ['large_decrement', 'small_decrement', 'none', 'large_increment', 'small_increment']         ;
+
+                                                                           
+                                                                                           
+                
+                                               
+                                 
+                        
+                       
+  
+
+                                 
+                      
+                     
+                             
+  
+
+class WindowsUiaSidecarClient {
+  #binaryPath        ;
+  #timeoutMs        ;
+  #process                                 ;
+  #pending = new Map                 ();
+  #starting                ;
+  #stderrTail           = [];
+
+  constructor(binaryPath        , timeoutMs = DEFAULT_TIMEOUT_MS) {
+    this.#binaryPath = path.resolve(binaryPath);
+    this.#timeoutMs = Math.min(Math.max(timeoutMs, 1_000), 120_000);
+  }
+
+  async call(method        , params         , signal              )                   {
+    if (signal?.aborted) throw new OperatorError('EXECUTION_ABORTED', 'Windows UIA execution was cancelled.', { retryable: false });
+    await this.#ensureStarted();
+    if (signal?.aborted) throw new OperatorError('EXECUTION_ABORTED', 'Windows UIA execution was cancelled.', { retryable: false });
+    const child = this.#process;
+    if (!child || child.exitCode !== null || child.stdin.destroyed) {
+      throw new OperatorError('UIA_SIDECAR_UNAVAILABLE', 'Windows UIA sidecar is not running.', { retryable: true });
+    }
+
+    const id = crypto.randomUUID();
+    const payload = JSON.stringify({ id, method, params });
+    if (Buffer.byteLength(payload) > 256 * 1024) {
+      throw new OperatorError('UIA_REQUEST_TOO_LARGE', 'Windows UIA request exceeds 256 KiB.');
+    }
+
+    const response = await new Promise                 ((resolve, reject) => {
+      let cleanupAbort = () => {};
+      const timer = setTimeout(() => {
+        this.#pending.delete(id);
+        cleanupAbort();
+        reject(new OperatorError('UIA_SIDECAR_TIMEOUT', `${method} timed out.`, { retryable: true }));
+      }, this.#timeoutMs);
+      const onAbort = () => {
+        clearTimeout(timer);
+        this.#pending.delete(id);
+        cleanupAbort();
+        reject(new OperatorError('EXECUTION_ABORTED', 'Windows UIA execution was cancelled.', { retryable: false }));
+        this.close();
+      };
+      cleanupAbort = () => signal?.removeEventListener('abort', onAbort);
+      this.#pending.set(id, { resolve, reject, timer, cleanup: cleanupAbort });
+      signal?.addEventListener('abort', onAbort, { once: true });
+      if (signal?.aborted) {
+        onAbort();
+        return;
+      }
+      child.stdin.write(`${payload}\n`, (error) => {
+        if (!error) return;
+        clearTimeout(timer);
+        this.#pending.delete(id);
+        cleanupAbort();
+        reject(new OperatorError('UIA_SIDECAR_WRITE_FAILED', error.message, { retryable: true }));
+      });
+    });
+
+    if (!response.ok) {
+      throw new OperatorError(
+        response.error?.code ?? 'UIA_OPERATION_FAILED',
+        response.error?.message ?? 'Windows UIA operation failed.',
+        { retryable: response.error?.retryable === true }
+      );
+    }
+    return response.result;
+  }
+
+  close()       {
+    const child = this.#process;
+    this.#process = undefined;
+    this.#starting = undefined;
+    const error = new OperatorError('UIA_SIDECAR_CLOSED', 'Windows UIA sidecar closed.', { retryable: true });
+    for (const pending of this.#pending.values()) {
+      clearTimeout(pending.timer);
+      pending.cleanup?.();
+      pending.reject(error);
+    }
+    this.#pending.clear();
+    if (child && child.exitCode === null && !child.killed) {
+      try { child.kill('SIGTERM'); } catch { /* noop */ }
+    }
+  }
+
+  async #ensureStarted()                {
+    if (this.#process && this.#process.exitCode === null) return;
+    if (this.#starting) return this.#starting;
+    this.#starting = this.#start();
+    try { await this.#starting; } finally { this.#starting = undefined; }
+  }
+
+  async #start()                {
+    const child = spawn(this.#binaryPath, [], {
+      shell: false,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
+      env: safeChildEnvironment('windows-native')
+    });
+    this.#process = child;
+
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk        ) => {
+      for (const line of chunk.split(/\r?\n/).filter(Boolean)) {
+        this.#stderrTail.push(line.slice(0, 1000));
+        if (this.#stderrTail.length > 20) this.#stderrTail.shift();
+      }
+    });
+
+    const lines = readline.createInterface({ input: child.stdout, crlfDelay: Infinity });
+    lines.on('line', (line) => {
+      if (Buffer.byteLength(line) > MAX_RESPONSE_LINE_BYTES) {
+        this.close();
+        return;
+      }
+      let response                 ;
+      try { response = JSON.parse(line)                   ; } catch { return; }
+      if (!response?.id) return;
+      const pending = this.#pending.get(response.id);
+      if (!pending) return;
+      clearTimeout(pending.timer);
+      pending.cleanup?.();
+      this.#pending.delete(response.id);
+      pending.resolve(response);
+    });
+
+    child.once('exit', (code, signal) => {
+      if (this.#process === child) this.#process = undefined;
+      const details = this.#stderrTail.slice(-5).join(' | ');
+      const error = new OperatorError(
+        'UIA_SIDECAR_EXITED',
+        `Windows UIA sidecar exited (${code ?? signal ?? 'unknown'}).${details ? ` ${details}` : ''}`,
+        { retryable: true }
+      );
+      for (const pending of this.#pending.values()) {
+        clearTimeout(pending.timer);
+        pending.cleanup?.();
+        pending.reject(error);
+      }
+      this.#pending.clear();
+    });
+
+    await new Promise      ((resolve, reject) => {
+      const timer = setTimeout(() => reject(new OperatorError('UIA_SIDECAR_START_TIMEOUT', 'Windows UIA sidecar did not become ready.', { retryable: true })), 5_000);
+      child.once('spawn', () => {
+        clearTimeout(timer);
+        resolve();
+      });
+      child.once('error', (error) => {
+        clearTimeout(timer);
+        reject(new OperatorError('UIA_SIDECAR_START_FAILED', error.message, { retryable: false }));
+      });
+    });
+
+    try {
+      await this.call('health', {});
+    } catch (error) {
+      this.close();
+      throw error;
+    }
+  }
+}
+
+export class WindowsUiaProvider                               {
+           name = 'windows.uia';
+  #platform                 ;
+  #client                         ;
+
+  constructor(options                    = {}) {
+    this.#platform = options.platform ?? process.platform;
+    const binary = options.binaryPath
+      ?? process.env.OPERATOR_WINDOWS_UIA_PATH
+      ?? path.join(process.cwd(), 'native', 'windows-uia', 'target', 'release', 'operator-windows-uia.exe');
+    this.#client = new WindowsUiaSidecarClient(binary, options.timeoutMs);
+  }
+
+  supports(action               )          {
+    return this.#platform === 'win32' && ['app.inspect', 'app.operate'].includes(action.capability);
+  }
+
+  score()                  { return SCORE; }
+
+  async execute(action               , context                             = {})                        {
+    const started = performance.now();
+    try {
+      const output = action.capability === 'app.inspect'
+        ? await this.#client.call('inspect', normalizeInspectInput(action.input), context.signal)
+        : await this.#client.call('operate', normalizeOperateInput(action.input), context.signal);
+      const postcondition = action.capability === 'app.operate'
+        ? evidence('postcondition', 'pass', 'Windows UIA/Win32 operation returned verified semantic postcondition evidence.', { operation: action.input.operation, waitMs: normalizeWaitMs(action.input.waitMs) })
+        : evidence('data_minimization', 'pass', 'Windows UIA returned a bounded semantic control tree, optional scoped events, and opt-in top-level window metadata instead of screenshots or process internals.', {
+            observeMs: normalizeObserveMs(action.input.observeMs),
+            waitMs: normalizeWaitMs(action.input.waitMs),
+            includeWindows: action.input.includeWindows === true,
+            maxWindows: normalizeMaxWindows(action.input.maxWindows)
+          });
+      return {
+        ok: true,
+        capability: action.capability,
+        provider: this.name,
+        output,
+        evidence: [
+          evidence('windows_uia', 'pass', action.capability === 'app.inspect' ? 'Inspected Windows controls through Microsoft UI Automation and optional bounded Win32 discovery.' : 'Operated Windows control through a verified UI Automation or semantic Win32 operation.', {}),
+          postcondition
+        ],
+        durationMs: Math.round(performance.now() - started)
+      };
+    } catch (error) {
+      const op = error instanceof OperatorError
+        ? error
+        : new OperatorError('UIA_PROVIDER_FAILED', error instanceof Error ? error.message : String(error), { retryable: true });
+      return {
+        ok: false,
+        capability: action.capability,
+        provider: this.name,
+        evidence: [evidence('windows_uia', 'fail', op.message, { code: op.code })],
+        error: { code: op.code, message: op.message, retryable: op.retryable },
+        durationMs: Math.round(performance.now() - started)
+      };
+    }
+  }
+
+  close()       { this.#client.close(); }
+}
+
+function normalizeSelector(input         ) {
+  const raw = input && typeof input === 'object' ? input                            : {};
+  const text = (key        ) => typeof raw[key] === 'string' ? String(raw[key]).trim().slice(0, 512) || undefined : undefined;
+  const processId = Number.isInteger(raw.processId) && Number(raw.processId) > 0 ? Number(raw.processId) : undefined;
+  return {
+    name: text('name'),
+    automation_id: text('automationId'),
+    class_name: text('className'),
+    control_type: text('controlType'),
+    process_id: processId
+  };
+}
+
+function normalizeObserveMs(value         )         {
+  return Number.isInteger(value) ? Math.min(Math.max(Number(value), 0), MAX_OBSERVE_MS) : 0;
+}
+
+function normalizeWaitMs(value         )         {
+  return Number.isInteger(value) ? Math.min(Math.max(Number(value), 0), MAX_WAIT_MS) : 0;
+}
+
+function normalizeMaxWindows(value         )         {
+  return Number.isInteger(value) ? Math.min(Math.max(Number(value), 1), MAX_WINDOWS) : DEFAULT_MAX_WINDOWS;
+}
+
+function normalizeInspectInput(input                         ) {
+  return {
+    selector: input.selector ? normalizeSelector(input.selector) : undefined,
+    max_nodes: Number.isInteger(input.maxNodes) ? Number(input.maxNodes) : undefined,
+    max_depth: Number.isInteger(input.maxDepth) ? Number(input.maxDepth) : undefined,
+    observe_ms: normalizeObserveMs(input.observeMs),
+    wait_ms: normalizeWaitMs(input.waitMs),
+    include_windows: input.includeWindows === true,
+    max_windows: normalizeMaxWindows(input.maxWindows)
+  };
+}
+
+function normalizeScrollAmount(value         , field        )                     {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string' || !(SCROLL_AMOUNTS                     ).includes(value)) {
+    throw new OperatorError('INVALID_UIA_SCROLL_AMOUNT', `${field} must be one of ${SCROLL_AMOUNTS.join(', ')}.`);
+  }
+  return value;
+}
+
+function normalizeOperateInput(input                         ) {
+  const operation = String(input.operation ?? '');
+  if (!(UIA_OPERATIONS                     ).includes(operation)) {
+    throw new OperatorError('INVALID_UIA_OPERATION', `operation must be ${UIA_OPERATIONS.join(', ')}.`);
+  }
+  const horizontalAmount = normalizeScrollAmount(input.horizontalAmount, 'horizontalAmount');
+  const verticalAmount = normalizeScrollAmount(input.verticalAmount, 'verticalAmount');
+  if (operation === 'scroll' && horizontalAmount === undefined && verticalAmount === undefined) {
+    throw new OperatorError('INVALID_UIA_SCROLL_AMOUNT', 'scroll requires horizontalAmount or verticalAmount.');
+  }
+  return {
+    operation,
+    selector: normalizeSelector(input.selector),
+    value: input.value === undefined ? undefined : String(input.value),
+    horizontal_amount: horizontalAmount,
+    vertical_amount: verticalAmount,
+    wait_ms: normalizeWaitMs(input.waitMs)
+  };
+}