@moretea-labs/forge 1.6.0 → 1.7.0

package/src/runtime/plugins/browser-macos-bridge.ts

@@ -1,10 +1,12 @@
 import { execFile } from 'child_process';
-import { existsSync, writeFileSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
+import { basename, extname } from 'path';
 import {
   callBrowserAutomationBroker,
   captureBrowserAutomationRegion,
   type BrowserAutomationBrokerAction,
+  type BrowserAutomationTrustedInput,
 } from './browser-automation-service';
 import { AssistantPluginError } from './errors';
 
@@ -41,6 +43,20 @@ export interface MacOsBrowserMetadata {
   loading?: boolean;
 }
 
+export interface MacOsBrowserTabInventoryEntry {
+  windowId: string;
+  tabId: string;
+  url: string;
+  title: string;
+  active: boolean;
+}
+
+export interface MacOsBrowserTabInventory {
+  product: MacOsBrowserProduct;
+  tabs: MacOsBrowserTabInventoryEntry[];
+  truncated: boolean;
+}
+
 export interface MacOsBrowserAttachAttempt {
   product: MacOsBrowserProduct;
   appName: string;
@@ -74,7 +90,9 @@ interface MacOsBrowserRuntimeHooks {
   // Test-only escape hatches. Production intentionally leaves these undefined so
   // Apple Events and screen capture are attributed to the stable helper process.
   runAppleScript?: (script: string, args: string[], timeoutMs: number) => Promise<string>;
+  tabInventory?: (product: MacOsBrowserProduct, timeoutMs: number) => Promise<MacOsBrowserTabInventory>;
   captureRegion?: (region: { x: number; y: number; width: number; height: number }, path: string, timeoutMs: number) => Promise<Buffer>;
+  trustedInput?: (request: Extract<BrowserAutomationBrokerAction, { action: 'trusted_input' }>, timeoutMs: number) => Promise<void>;
 }
 
 function execFileText(file: string, args: string[], timeoutMs: number): Promise<string> {
@@ -143,8 +161,72 @@ async function captureBrowserAutomation(
   return bytes;
 }
 
+async function sendBrowserTrustedInput(
+  request: Extract<BrowserAutomationBrokerAction, { action: 'trusted_input' }>,
+  timeoutMs: number,
+): Promise<void> {
+  if (runtimeHooks.trustedInput) {
+    await runtimeHooks.trustedInput(request, timeoutMs);
+    return;
+  }
+  let result: Record<string, unknown>;
+  try {
+    result = await callBrowserAutomationBroker(request, timeoutMs);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error ?? '');
+    if ((error instanceof AssistantPluginError && error.code === 'BROWSER_AUTOMATION_ACTION_UNSUPPORTED')
+      || /\bBROWSER_AUTOMATION_ACTION_UNSUPPORTED\b/.test(message)) {
+      throw new AssistantPluginError(
+        'PLUGIN_BROWSER_TRUSTED_INPUT_UNAVAILABLE',
+        'Installed Forge Desktop Operator does not support native browser trusted input. Keep the exact tab explicitly foregrounded and use a separately grounded Desktop Operator interaction, or upgrade the stable Desktop Operator provider.',
+        { retryable: false, details: { browserProduct: request.product, requiredProviderAction: 'trusted_input' } },
+      );
+    }
+    throw error;
+  }
+  if (result.performed !== true) {
+    throw new AssistantPluginError(
+      'PLUGIN_MACOS_CAPABILITY_BROKER_PROTOCOL_ERROR',
+      'Stable Forge macOS capability broker did not confirm trusted browser input.',
+      { retryable: true },
+    );
+  }
+}
+
 let runtimeHooks: MacOsBrowserRuntimeHooks = { ...defaultRuntimeHooks };
 let lastAttachObservation: MacOsBrowserAttachObservation | undefined;
+const MAX_WARM_NATIVE_PAGE_HANDLES = 128;
+const warmNativePageHandles = new Map<string, MacOsAppleEventsPage>();
+
+function nativePageHandleKey(product: MacOsBrowserProduct, ref: MacOsBrowserTabRef): string {
+  // tabId is the stable browser entity. The windowId is only a mutable placement hint and
+  // is re-resolved from live inventory immediately before exact-target Apple Events operations.
+  return `${product}:${ref.tabId}`;
+}
+
+function rememberMacOsBrowserPageHandle(product: MacOsBrowserProduct, ref: MacOsBrowserTabRef, page: MacOsAppleEventsPage): void {
+  const key = nativePageHandleKey(product, ref);
+  warmNativePageHandles.delete(key);
+  warmNativePageHandles.set(key, page);
+  while (warmNativePageHandles.size > MAX_WARM_NATIVE_PAGE_HANDLES) {
+    const oldest = warmNativePageHandles.keys().next().value;
+    if (typeof oldest !== 'string') break;
+    warmNativePageHandles.delete(oldest);
+  }
+}
+
+export function invalidateMacOsBrowserPageHandle(product: MacOsBrowserProduct, ref: MacOsBrowserTabRef): void {
+  warmNativePageHandles.delete(nativePageHandleKey(product, ref));
+}
+
+export function invalidateMacOsBrowserPageHandles(): void {
+  warmNativePageHandles.clear();
+}
+
+export function macOsBrowserPageHandleStale(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error ?? '');
+  return /FORGE_BROWSER_TAB_NOT_FOUND|BROWSER_AUTOMATION_TAB_NOT_FOUND|target tab.*not found|can[’']t get tab .*invalid index.*-1719/i.test(message);
+}
 
 export function setMacOsBrowserRuntimeHooksForTest(hooks: Partial<MacOsBrowserRuntimeHooks>): void {
   runtimeHooks = { ...defaultRuntimeHooks, ...hooks };
@@ -153,6 +235,7 @@ export function setMacOsBrowserRuntimeHooksForTest(hooks: Partial<MacOsBrowserRu
 export function resetMacOsBrowserRuntimeHooksForTest(): void {
   runtimeHooks = { ...defaultRuntimeHooks };
   lastAttachObservation = undefined;
+  warmNativePageHandles.clear();
 }
 
 export function getMacOsBrowserAttachObservation(): MacOsBrowserAttachObservation | undefined {
@@ -197,12 +280,120 @@ set targetWindow to front window
 set targetTab to active tab of targetWindow
 set windowBounds to bounds of targetWindow
 set separator to ASCII character 30
-return (frontmost as text) & separator & (URL of targetTab as text) & separator & (title of targetTab as text) & separator & ((item 1 of windowBounds) as text) & separator & ((item 2 of windowBounds) as text) & separator & ((item 3 of windowBounds) as text) & separator & ((item 4 of windowBounds) as text)
+return (frontmost as text) & separator & (URL of targetTab as text) & separator & (title of targetTab as text) & separator & ((item 1 of windowBounds) as text) & separator & ((item 2 of windowBounds) as text) & separator & ((item 3 of windowBounds) as text) & separator & ((item 4 of windowBounds) as text) & separator & ((id of targetWindow) as text) & separator & ((id of targetTab) as text) & separator & "true" & separator & (loading of targetTab as text)
 `);
 }
 
+function listTabsScript(browser: MacOsBrowserDefinition): string {
+  return `on replaceText(sourceText, needle, replacement)
+  set previousDelimiters to AppleScript's text item delimiters
+  set AppleScript's text item delimiters to needle
+  set sourceItems to every text item of sourceText
+  set AppleScript's text item delimiters to replacement
+  set resultText to sourceItems as text
+  set AppleScript's text item delimiters to previousDelimiters
+  return resultText
+end replaceText
+
+on cleanField(sourceText, recordSeparator, fieldSeparator)
+  set cleaned to my replaceText(sourceText as text, recordSeparator, " ")
+  return my replaceText(cleaned, fieldSeparator, " ")
+end cleanField
+
+${browserTellScript(browser, `
+set recordSeparator to ASCII character 30
+set fieldSeparator to ASCII character 31
+set maxTabs to 256
+set returnedCount to 0
+set truncatedInventory to false
+set outputText to "false"
+repeat with candidateWindow in windows
+  set activeTabId to ""
+  try
+    set activeTabId to ((id of active tab of candidateWindow) as text)
+  end try
+  repeat with candidateTab in tabs of candidateWindow
+    if returnedCount is greater than or equal to maxTabs then
+      set truncatedInventory to true
+      exit repeat
+    end if
+    set candidateWindowId to ((id of candidateWindow) as text)
+    set candidateTabId to ((id of candidateTab) as text)
+    set candidateURL to my cleanField((URL of candidateTab as text), recordSeparator, fieldSeparator)
+    set candidateTitle to my cleanField((title of candidateTab as text), recordSeparator, fieldSeparator)
+    set candidateActive to (candidateTabId is activeTabId)
+    set outputText to outputText & recordSeparator & candidateWindowId & fieldSeparator & candidateTabId & fieldSeparator & (candidateActive as text) & fieldSeparator & candidateURL & fieldSeparator & candidateTitle
+    set returnedCount to returnedCount + 1
+  end repeat
+  if truncatedInventory then exit repeat
+end repeat
+if truncatedInventory then
+  set outputText to "true" & text 6 thru -1 of outputText
+end if
+return outputText
+`)}
+`;
+}
+
+function parseTabInventory(product: MacOsBrowserProduct, raw: string): MacOsBrowserTabInventory {
+  const records = raw.split(RECORD_SEPARATOR);
+  const marker = (records.shift() ?? '').trim().toLowerCase();
+  if (marker !== 'true' && marker !== 'false') {
+    throw new AssistantPluginError(
+      'PLUGIN_MACOS_CAPABILITY_BROKER_PROTOCOL_ERROR',
+      'Stable Forge macOS capability broker returned an invalid browser tab inventory marker.',
+      { retryable: true },
+    );
+  }
+  const tabs: MacOsBrowserTabInventoryEntry[] = [];
+  const fieldSeparator = String.fromCharCode(31);
+  for (const record of records) {
+    if (!record) continue;
+    const fields = record.split(fieldSeparator);
+    if (fields.length < 5) {
+      throw new AssistantPluginError(
+        'PLUGIN_MACOS_CAPABILITY_BROKER_PROTOCOL_ERROR',
+        'Stable Forge macOS capability broker returned incomplete browser tab inventory metadata.',
+        { retryable: true },
+      );
+    }
+    const windowId = (fields[0] ?? '').trim();
+    const tabId = (fields[1] ?? '').trim();
+    const activeText = (fields[2] ?? '').trim().toLowerCase();
+    if (!windowId || !tabId || (activeText !== 'true' && activeText !== 'false')) {
+      throw new AssistantPluginError(
+        'PLUGIN_MACOS_CAPABILITY_BROKER_PROTOCOL_ERROR',
+        'Stable Forge macOS capability broker returned invalid browser tab inventory metadata.',
+        { retryable: true },
+      );
+    }
+    tabs.push({ windowId, tabId, active: activeText === 'true', url: fields[3] ?? '', title: fields.slice(4).join(fieldSeparator) });
+    if (tabs.length > 256) {
+      throw new AssistantPluginError(
+        'PLUGIN_MACOS_CAPABILITY_BROKER_PROTOCOL_ERROR',
+        'Stable Forge macOS capability broker exceeded the bounded browser tab inventory size.',
+        { retryable: true },
+      );
+    }
+  }
+  return { product, tabs, truncated: marker === 'true' };
+}
+
 function targetTabPreamble(ref: MacOsBrowserTabRef): string {
-  return `set targetWindow to first window whose id is ${quotedAppleScript(ref.windowId)}\nset targetTab to first tab of targetWindow whose id is ${quotedAppleScript(ref.tabId)}`;
+  return `set targetTabId to ${quotedAppleScript(ref.tabId)}
+set targetWindow to missing value
+set targetTab to missing value
+repeat with candidateWindow in windows
+  repeat with candidateTab in tabs of candidateWindow
+    if ((id of candidateTab) as text) is targetTabId then
+      set targetWindow to candidateWindow
+      set targetTab to candidateTab
+      exit repeat
+    end if
+  end repeat
+  if targetTab is not missing value then exit repeat
+end repeat
+if targetTab is missing value then error "FORGE_BROWSER_TAB_NOT_FOUND:" & targetTabId`;
 }
 
 function targetMetadataScript(browser: MacOsBrowserDefinition, ref: MacOsBrowserTabRef): string {
@@ -211,7 +402,7 @@ ${targetTabPreamble(ref)}
 set windowBounds to bounds of targetWindow
 set separator to ASCII character 30
 set targetIsActive to ((id of active tab of targetWindow) is (id of targetTab))
-return (frontmost as text) & separator & (URL of targetTab as text) & separator & "" & separator & ((item 1 of windowBounds) as text) & separator & ((item 2 of windowBounds) as text) & separator & ((item 3 of windowBounds) as text) & separator & ((item 4 of windowBounds) as text) & separator & "" & separator & "" & separator & (targetIsActive as text) & separator & (loading of targetTab as text)
+return (frontmost as text) & separator & (URL of targetTab as text) & separator & "" & separator & ((item 1 of windowBounds) as text) & separator & ((item 2 of windowBounds) as text) & separator & ((item 3 of windowBounds) as text) & separator & ((item 4 of windowBounds) as text) & separator & ((id of targetWindow) as text) & separator & ((id of targetTab) as text) & separator & (targetIsActive as text) & separator & (loading of targetTab as text)
 `);
 }
 
@@ -416,7 +607,8 @@ function serializeEvaluation(expression: string | ((...args: unknown[]) => unkno
   return `(() => {
     try {
       const value = (${source});
-      return JSON.stringify({ ok: true, value: value === undefined ? { __forgeUndefined: true } : value });
+      const page = { url: String(document.location.href || ''), title: String(document.title || '') };
+      return JSON.stringify({ ok: true, value: value === undefined ? { __forgeUndefined: true } : value, page });
     } catch (error) {
       return JSON.stringify({ ok: false, error: String(error && (error.stack || error.message) || error) });
     }
@@ -464,11 +656,23 @@ function keyEventSource(selector: string | undefined, keySpec: string): string {
   })()`;
 }
 
+export function nativeDomLoadStateSatisfied(
+  state: string,
+  readyState: string,
+  currentUrl: string,
+  requireHttpUrl: boolean,
+): boolean {
+  if (requireHttpUrl && !/^https?:\/\//i.test(currentUrl ?? '')) return false;
+  return state === 'load' || state === 'networkidle'
+    ? readyState === 'complete'
+    : readyState === 'interactive' || readyState === 'complete';
+}
+
 export class MacOsAppleEventsPage {
   private metadata: MacOsBrowserMetadata;
   private readonly browser: MacOsBrowserDefinition;
-  private readonly timeoutMs: number;
-  private readonly targetRef?: MacOsBrowserTabRef;
+  private timeoutMs: number;
+  private targetRef?: MacOsBrowserTabRef;
 
   constructor(attachment: MacOsBrowserAttachment, timeoutMs = DEFAULT_NATIVE_TIMEOUT_MS, targetRef?: MacOsBrowserTabRef) {
     this.metadata = { ...attachment.metadata, ...(targetRef ? { windowId: targetRef.windowId, tabId: targetRef.tabId } : {}) };
@@ -479,12 +683,20 @@ export class MacOsAppleEventsPage {
 
   private async runAutomation(
     request: BrowserAutomationBrokerAction,
-    script: string,
+    script: string | ((resolvedRef?: MacOsBrowserTabRef) => string),
     args: string[] = [],
     timeoutMs = this.timeoutMs,
   ): Promise<string> {
     try {
-      return await runBrowserAutomationText(request, script, args, timeoutMs);
+      let effectiveRequest = request;
+      let resolvedRef: MacOsBrowserTabRef | undefined;
+      if ('ref' in request && request.ref) {
+        resolvedRef = await resolveCurrentMacOsBrowserTabRef(this.browser.product, request.ref, timeoutMs);
+        this.targetRef = resolvedRef;
+        effectiveRequest = { ...request, ref: resolvedRef } as BrowserAutomationBrokerAction;
+      }
+      const effectiveScript = typeof script === 'function' ? script(resolvedRef ?? this.targetRef) : script;
+      return await runBrowserAutomationText(effectiveRequest, effectiveScript, args, timeoutMs);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       throw new AssistantPluginError('PLUGIN_BROWSER_NATIVE_OPERATION_FAILED', `${this.browser.appName} Apple Events operation failed: ${message}`, {
@@ -495,11 +707,13 @@ export class MacOsAppleEventsPage {
   }
 
   private async refreshMetadata(): Promise<MacOsBrowserMetadata> {
-    const script = this.targetRef ? targetMetadataScript(this.browser, this.targetRef) : metadataScript(this.browser);
     this.metadata = parseMetadata(this.browser.product, await this.runAutomation(
       { action: 'metadata', product: this.browser.product, ...(this.targetRef ? { ref: this.targetRef } : {}) },
-      script,
+      (resolvedRef) => resolvedRef ? targetMetadataScript(this.browser, resolvedRef) : metadataScript(this.browser),
     ));
+    if (this.targetRef && this.metadata.windowId && this.metadata.tabId) {
+      this.targetRef = { windowId: this.metadata.windowId, tabId: this.metadata.tabId };
+    }
     return this.metadata;
   }
 
@@ -507,7 +721,7 @@ export class MacOsAppleEventsPage {
     try {
       return await this.runAutomation(
         { action: 'execute_javascript', product: this.browser.product, ...(this.targetRef ? { ref: this.targetRef } : {}), source },
-        executeJavaScriptScript(this.browser, this.targetRef),
+        (resolvedRef) => executeJavaScriptScript(this.browser, resolvedRef),
         [source],
         timeoutMs,
       );
@@ -527,18 +741,28 @@ export class MacOsAppleEventsPage {
     return this.targetRef ? { ...this.targetRef } : undefined;
   }
 
+  updateTimeout(timeoutMs: number): void {
+    if (Number.isFinite(timeoutMs) && timeoutMs > 0) this.timeoutMs = Math.trunc(timeoutMs);
+  }
+
+  attachmentSnapshot(): MacOsBrowserAttachment {
+    return {
+      metadata: { ...this.metadata, bounds: { ...this.metadata.bounds } },
+      attempts: [{
+        product: this.browser.product,
+        appName: this.browser.appName,
+        bundleId: this.browser.bundleId,
+        status: 'selected',
+        frontmost: this.metadata.frontmost,
+      }],
+    };
+  }
+
   async goto(url: string, options: Record<string, unknown> = {}): Promise<unknown> {
     const timeout = typeof options.timeout === 'number' ? Math.trunc(options.timeout) : this.timeoutMs;
-    if (this.targetRef) {
-      throw new AssistantPluginError(
-        'PLUGIN_BROWSER_BACKGROUND_NAVIGATION_REQUIRES_REPLACEMENT',
-        'Chrome/Vivaldi background tabs cannot be navigated reliably in place through Apple Events; create a replacement plugin-owned tab instead.',
-        { retryable: true, details: { browserProduct: this.browser.product, windowId: this.targetRef.windowId, tabId: this.targetRef.tabId } },
-      );
-    }
     await this.runAutomation(
-      { action: 'navigate', product: this.browser.product, url },
-      navigateScript(this.browser),
+      { action: 'navigate', product: this.browser.product, ...(this.targetRef ? { ref: this.targetRef } : {}), url },
+      (resolvedRef) => navigateScript(this.browser, resolvedRef),
       [url],
       timeout,
     );
@@ -551,7 +775,7 @@ export class MacOsAppleEventsPage {
     const timeout = typeof options.timeout === 'number' ? Math.trunc(options.timeout) : this.timeoutMs;
     await this.runAutomation(
       { action: 'reload', product: this.browser.product, ...(this.targetRef ? { ref: this.targetRef } : {}) },
-      reloadScript(this.browser, this.targetRef),
+      (resolvedRef) => reloadScript(this.browser, resolvedRef),
       [],
       timeout,
     );
@@ -609,21 +833,183 @@ export class MacOsAppleEventsPage {
 
   async evaluate<T>(expression: string | ((...args: unknown[]) => unknown), arg?: unknown): Promise<T> {
     const raw = await this.executeJavaScriptRaw(serializeEvaluation(expression, arg));
-    let parsed: { ok?: boolean; value?: unknown; error?: string };
+    let parsed: { ok?: boolean; value?: unknown; error?: string; page?: { url?: unknown; title?: unknown } };
     try {
-      parsed = JSON.parse(raw) as { ok?: boolean; value?: unknown; error?: string };
+      parsed = JSON.parse(raw) as { ok?: boolean; value?: unknown; error?: string; page?: { url?: unknown; title?: unknown } };
     } catch {
       throw new AssistantPluginError('PLUGIN_BROWSER_NATIVE_PROTOCOL_ERROR', `${this.browser.appName} returned an invalid JavaScript result.`, {
         retryable: true,
       });
     }
     if (!parsed.ok) throw new Error(parsed.error || 'Browser JavaScript evaluation failed.');
+    if (parsed.page && typeof parsed.page.url === 'string' && parsed.page.url) {
+      this.metadata = {
+        ...this.metadata,
+        url: parsed.page.url,
+        title: typeof parsed.page.title === 'string' ? parsed.page.title : this.metadata.title,
+      };
+    }
     if (parsed.value && typeof parsed.value === 'object' && (parsed.value as { __forgeUndefined?: unknown }).__forgeUndefined === true) {
       return undefined as T;
     }
     return parsed.value as T;
   }
 
+  async setInputFiles(selector: string, files: string | string[]): Promise<void> {
+    const filePaths = Array.isArray(files) ? files : [files];
+    if (filePaths.length === 0 || filePaths.length > 32) {
+      throw new AssistantPluginError('PLUGIN_ACTION_ARGUMENT_INVALID', 'Native browser file input accepts 1-32 local files.', { retryable: false });
+    }
+    for (const filePath of filePaths) {
+      if (!filePath || !existsSync(filePath)) {
+        throw new AssistantPluginError('PLUGIN_ACTION_ARGUMENT_INVALID', 'Local file does not exist.', { retryable: false });
+      }
+    }
+
+    if (filePaths.length === 1) {
+      const filePath = filePaths[0];
+      const bytes = readFileSync(filePath);
+      const fileName = basename(filePath);
+      const extension = extname(fileName).toLowerCase();
+      const mimeType = extension === '.pdf' ? 'application/pdf'
+        : extension === '.zip' ? 'application/zip'
+        : extension === '.png' ? 'image/png'
+        : extension === '.jpg' || extension === '.jpeg' ? 'image/jpeg'
+        : 'application/octet-stream';
+      const bufferKey = `__forgeLocalFile_${Date.now()}_${Math.random().toString(16).slice(2)}`;
+      const encoded = bytes.toString('base64');
+      const chunkChars = 192 * 1024;
+      try {
+        await this.evaluate(`(() => { globalThis[${JSON.stringify(bufferKey)}] = ''; return true; })()`);
+        for (let offset = 0; offset < encoded.length; offset += chunkChars) {
+          const chunk = encoded.slice(offset, offset + chunkChars);
+          await this.evaluate(`(() => { globalThis[${JSON.stringify(bufferKey)}] += ${JSON.stringify(chunk)}; return true; })()`);
+        }
+        const attached = await this.evaluate<{ name?: string; size?: number }>(`(() => {
+          const element = document.querySelector(${JSON.stringify(selector)});
+          if (!(element instanceof HTMLInputElement) || element.type !== 'file') throw new Error('Selector must resolve to an input[type=file].');
+          const expectedName = ${JSON.stringify(fileName)};
+          const expectedSize = ${bytes.length};
+          const encoded = String(globalThis[${JSON.stringify(bufferKey)}] || '');
+          const binary = atob(encoded);
+          const data = new Uint8Array(binary.length);
+          for (let i = 0; i < binary.length; i += 1) data[i] = binary.charCodeAt(i);
+          const file = new File([data], expectedName, { type: ${JSON.stringify(mimeType)} });
+          const transfer = new DataTransfer();
+          transfer.items.add(file);
+          element.files = transfer.files;
+          element.dispatchEvent(new Event('input', { bubbles: true }));
+          element.dispatchEvent(new Event('change', { bubbles: true }));
+          const selected = element.files && element.files[0];
+          return selected ? { name: selected.name, size: selected.size, expectedName, expectedSize } : null;
+        })()`);
+        if (attached?.name !== fileName || attached?.size !== bytes.length) {
+          throw new AssistantPluginError('PLUGIN_BROWSER_NATIVE_FILE_ATTACH_FAILED', 'Native browser did not retain the requested local file on the target input.', {
+            retryable: true,
+            details: { expectedName: fileName, expectedSize: bytes.length, actualName: attached?.name, actualSize: attached?.size },
+          });
+        }
+      } finally {
+        await this.evaluate(`(() => { try { delete globalThis[${JSON.stringify(bufferKey)}]; } catch {} return true; })()`).catch(() => undefined);
+      }
+      return;
+    }
+
+    const attachments = filePaths.map((filePath) => {
+      const bytes = readFileSync(filePath);
+      const fileName = basename(filePath);
+      const extension = extname(fileName).toLowerCase();
+      const mimeType = extension === '.pdf' ? 'application/pdf'
+        : extension === '.zip' ? 'application/zip'
+        : extension === '.png' ? 'image/png'
+        : extension === '.jpg' || extension === '.jpeg' ? 'image/jpeg'
+        : 'application/octet-stream';
+      return {
+        bytes,
+        fileName,
+        mimeType,
+        bufferKey: `__forgeLocalFile_${Date.now()}_${Math.random().toString(16).slice(2)}`,
+      };
+    });
+
+    if (attachments.length > 1) {
+      await this.evaluate(`(() => {
+        const element = document.querySelector(${JSON.stringify(selector)});
+        if (!(element instanceof HTMLInputElement) || element.type !== 'file') throw new Error('Selector must resolve to an input[type=file].');
+        if (!element.multiple) throw new Error('Target input does not allow multiple files.');
+        const transfer = new DataTransfer();
+        element.files = transfer.files;
+        return true;
+      })()`);
+    }
+
+    const chunkChars = 192 * 1024;
+    try {
+      for (let index = 0; index < attachments.length; index += 1) {
+        const attachment = attachments[index];
+        const encoded = attachment.bytes.toString('base64');
+        await this.evaluate(`(() => { globalThis[${JSON.stringify(attachment.bufferKey)}] = ''; return true; })()`);
+        for (let offset = 0; offset < encoded.length; offset += chunkChars) {
+          const chunk = encoded.slice(offset, offset + chunkChars);
+          await this.evaluate(`(() => { globalThis[${JSON.stringify(attachment.bufferKey)}] += ${JSON.stringify(chunk)}; return true; })()`);
+        }
+        const append = attachments.length > 1 && index > 0;
+        await this.evaluate(`(() => {
+          const element = document.querySelector(${JSON.stringify(selector)});
+          if (!(element instanceof HTMLInputElement) || element.type !== 'file') throw new Error('Selector must resolve to an input[type=file].');
+          const expectedName = ${JSON.stringify(attachment.fileName)};
+          const expectedSize = ${attachment.bytes.length};
+          const encoded = String(globalThis[${JSON.stringify(attachment.bufferKey)}] || '');
+          const binary = atob(encoded);
+          const data = new Uint8Array(binary.length);
+          for (let i = 0; i < binary.length; i += 1) data[i] = binary.charCodeAt(i);
+          const file = new File([data], expectedName, { type: ${JSON.stringify(attachment.mimeType)} });
+          const transfer = new DataTransfer();
+          if (${append ? 'true' : 'false'}) {
+            for (const existing of Array.from(element.files || [])) transfer.items.add(existing);
+          }
+          transfer.items.add(file);
+          element.files = transfer.files;
+          return Array.from(element.files || []).map((selected) => ({ name: selected.name, size: selected.size }));
+        })()`);
+      }
+
+      const selected = await this.evaluate<Array<{ name?: string; size?: number }>>(`(() => {
+        const element = document.querySelector(${JSON.stringify(selector)});
+        if (!(element instanceof HTMLInputElement) || element.type !== 'file') throw new Error('Selector must resolve to an input[type=file].');
+        element.dispatchEvent(new Event('input', { bubbles: true }));
+        element.dispatchEvent(new Event('change', { bubbles: true }));
+        return Array.from(element.files || []).map((file) => ({ name: file.name, size: file.size }));
+      })()`);
+      const expected = attachments.map((attachment) => ({ name: attachment.fileName, size: attachment.bytes.length }));
+      const matches = selected.length === expected.length && expected.every((item, index) => selected[index]?.name === item.name && selected[index]?.size === item.size);
+      if (!matches) {
+        throw new AssistantPluginError('PLUGIN_BROWSER_NATIVE_FILE_ATTACH_FAILED', 'Native browser did not retain the requested local files on the target input.', {
+          retryable: true,
+          details: { expected, actual: selected },
+        });
+      }
+    } finally {
+      for (const attachment of attachments) {
+        await this.evaluate(`(() => { try { delete globalThis[${JSON.stringify(attachment.bufferKey)}]; } catch {} return true; })()`).catch(() => undefined);
+      }
+    }
+  }
+
+  async foregroundState(): Promise<{ frontmost: boolean; active: boolean }> {
+    const metadata = await this.refreshMetadata();
+    return { frontmost: metadata.frontmost, active: metadata.active === true };
+  }
+
+  async trustedInput(input: BrowserAutomationTrustedInput): Promise<void> {
+    if (!this.targetRef) {
+      throw new AssistantPluginError('PLUGIN_BROWSER_TRUSTED_INPUT_UNAVAILABLE', 'Native trusted input requires an exact saved browser tab.', { retryable: false });
+    }
+    this.targetRef = await resolveCurrentMacOsBrowserTabRef(this.browser.product, this.targetRef, this.timeoutMs);
+    await sendBrowserTrustedInput({ action: 'trusted_input', product: this.browser.product, ref: this.targetRef, input }, this.timeoutMs);
+    await this.refreshMetadata();
+  }
+
   async screenshot(options: Record<string, unknown>): Promise<Buffer> {
     const path = typeof options.path === 'string' ? options.path : undefined;
     if (!path) throw new Error('Native browser screenshot requires an output path.');
@@ -638,7 +1024,40 @@ export class MacOsAppleEventsPage {
   }
 
   async click(selector: string): Promise<void> {
-    await this.evaluate(selectorSource(selector, 'if (typeof element.click !== "function") throw new Error("Element is not clickable."); element.click(); return true;'));
+    await this.evaluate(selectorSource(selector, `
+      if (element instanceof HTMLOptionElement) {
+        const selectElement = element.closest('select');
+        if (!(selectElement instanceof HTMLSelectElement)) throw new Error('Option is not attached to a select.');
+        if (element.disabled || selectElement.disabled) throw new Error('Option is disabled.');
+        if (!selectElement.multiple) {
+          const valueSetter = Object.getOwnPropertyDescriptor(HTMLSelectElement.prototype, 'value')?.set;
+          if (valueSetter) valueSetter.call(selectElement, element.value);
+          else selectElement.value = element.value;
+        } else {
+          element.selected = true;
+        }
+        selectElement.dispatchEvent(new Event('input', { bubbles: true }));
+        selectElement.dispatchEvent(new Event('change', { bubbles: true }));
+        if (!Array.from(selectElement.selectedOptions).includes(element)) throw new Error('Option selection did not persist.');
+        return true;
+      }
+      if (typeof element.click !== "function") throw new Error("Element is not clickable.");
+      const rect = typeof element.getBoundingClientRect === 'function' ? element.getBoundingClientRect() : { left: 0, top: 0, width: 0, height: 0 };
+      const clientX = Number(rect.left || 0) + Number(rect.width || 0) / 2;
+      const clientY = Number(rect.top || 0) + Number(rect.height || 0) / 2;
+      const mouseInit = { bubbles: true, cancelable: true, composed: true, view: window, button: 0, buttons: 1, clientX, clientY };
+      if (typeof PointerEvent === 'function') {
+        element.dispatchEvent(new PointerEvent('pointerdown', { ...mouseInit, pointerId: 1, pointerType: 'mouse', isPrimary: true }));
+      }
+      element.dispatchEvent(new MouseEvent('mousedown', mouseInit));
+      if (typeof element.focus === 'function') element.focus();
+      if (typeof PointerEvent === 'function') {
+        element.dispatchEvent(new PointerEvent('pointerup', { ...mouseInit, buttons: 0, pointerId: 1, pointerType: 'mouse', isPrimary: true }));
+      }
+      element.dispatchEvent(new MouseEvent('mouseup', { ...mouseInit, buttons: 0 }));
+      element.click();
+      return true;
+    `));
   }
 
   async dblclick(selector: string): Promise<void> {
@@ -681,10 +1100,20 @@ export class MacOsAppleEventsPage {
     return await this.evaluate(selectorSource(selector, `
       if (!(element instanceof HTMLSelectElement)) throw new Error('Element is not a select.');
       const selected = new Set(${JSON.stringify(normalized)});
-      for (const option of element.options) option.selected = selected.has(option.value) || selected.has(option.label);
+      let matched = 0;
+      for (const option of element.options) {
+        const shouldSelect = selected.has(option.value) || selected.has(option.label);
+        option.selected = shouldSelect;
+        if (shouldSelect) matched += 1;
+      }
+      if (matched === 0) throw new Error('Requested select option was not found.');
       element.dispatchEvent(new Event('input', { bubbles: true }));
       element.dispatchEvent(new Event('change', { bubbles: true }));
-      return Array.from(element.selectedOptions).map((option) => option.value);
+      const actual = Array.from(element.selectedOptions);
+      if (!actual.some((option) => selected.has(option.value) || selected.has(option.label))) {
+        throw new Error('Requested select option did not persist.');
+      }
+      return actual.map((option) => option.value);
     `));
   }
 
@@ -730,15 +1159,19 @@ export class MacOsAppleEventsPage {
 
   async waitForLoadState(state = 'domcontentloaded', options: Record<string, unknown> = {}): Promise<void> {
     const timeout = typeof options.timeout === 'number' ? Math.trunc(options.timeout) : this.timeoutMs;
+    const requireHttpUrl = options.requireHttpUrl === true;
     const deadline = Date.now() + timeout;
     while (Date.now() <= deadline) {
       if (this.targetRef) {
         try {
           const metadata = await this.refreshMetadata();
-          const transitionalUrl = !metadata.url
-            || metadata.url === 'about:blank'
-            || metadata.url === 'chrome://newtab/'
-            || metadata.url === 'vivaldi://newtab/';
+          // Browser actions only admit HTTP(S) targets. Native Chrome/Vivaldi can
+          // expose several internal URLs (new-tab, error/interstitial, extension
+          // bootstrap pages) while navigation is still settling. Treat every
+          // non-HTTP(S) metadata URL as transitional here; the adapter still
+          // applies the strict final HTTP(S) URL validator before persisting a
+          // session, so this does not widen the accepted navigation surface.
+          const transitionalUrl = !/^https?:\/\//i.test(metadata.url ?? '');
           if (transitionalUrl) {
             await new Promise((resolve) => setTimeout(resolve, 100));
             continue;
@@ -749,14 +1182,14 @@ export class MacOsAppleEventsPage {
         }
       }
       try {
-        const readyState = await this.evaluate<string>('document.readyState');
-        if (state === 'load' || state === 'networkidle') {
-          if (readyState === 'complete') return;
-        } else if (readyState === 'interactive' || readyState === 'complete') return;
+        const domState = await this.evaluate<{ readyState: string; url: string }>(
+          '({ readyState: String(document.readyState || ""), url: String(document.location.href || "") })',
+        );
+        if (nativeDomLoadStateSatisfied(state, domState.readyState, domState.url, requireHttpUrl)) return;
       } catch (error) {
         if (error instanceof AssistantPluginError && error.code === 'PLUGIN_BROWSER_JAVASCRIPT_PERMISSION_REQUIRED') {
           const metadata = await this.refreshMetadata();
-          if (metadata.url && metadata.url !== 'about:blank' && metadata.url !== 'chrome://newtab/' && metadata.url !== 'vivaldi://newtab/') return;
+          if (/^https?:\/\//i.test(metadata.url ?? '')) return;
         }
         // Navigation can transiently invalidate the current JavaScript execution context.
       }
@@ -776,6 +1209,9 @@ export class MacOsAppleEventsPage {
   async bringToFront(): Promise<void> {
     if (this.targetRef) {
       this.metadata = await activateMacOsBrowserOwnedTab(this.browser.product, this.targetRef, this.timeoutMs);
+      if (this.metadata.windowId && this.metadata.tabId) {
+        this.targetRef = { windowId: this.metadata.windowId, tabId: this.metadata.tabId };
+      }
       return;
     }
     await this.runAutomation(
@@ -791,15 +1227,71 @@ export class MacOsAppleEventsPage {
   };
 }
 
+async function resolveCurrentMacOsBrowserTabRef(
+  product: MacOsBrowserProduct,
+  ref: MacOsBrowserTabRef,
+  timeoutMs = DEFAULT_NATIVE_TIMEOUT_MS,
+): Promise<MacOsBrowserTabRef> {
+  // Existing unit-level AppleScript hooks historically model one exact script at a time.
+  // Preserve that narrow test seam unless a live inventory hook is explicitly supplied;
+  // production always resolves through the stable Desktop Operator broker inventory.
+  const inventory = runtimeHooks.tabInventory
+    ? await runtimeHooks.tabInventory(product, timeoutMs)
+    : runtimeHooks.runAppleScript
+      ? undefined
+      : await listMacOsBrowserTabs(product, timeoutMs);
+  if (!inventory) return ref;
+
+  const matches = inventory.tabs.filter((candidate) => candidate.tabId === ref.tabId);
+  if (inventory.truncated || matches.length !== 1) {
+    throw new AssistantPluginError(
+      'PLUGIN_BROWSER_NATIVE_TAB_IDENTITY_UNPROVEN',
+      inventory.truncated
+        ? `Cannot prove the current ${product} tab identity because live inventory was truncated.`
+        : matches.length === 0
+          ? `Saved ${product} tab ${ref.tabId} no longer exists in live inventory.`
+          : `Saved ${product} tab ${ref.tabId} is ambiguous in live inventory.`,
+      {
+        retryable: true,
+        details: {
+          browserProduct: product,
+          tabId: ref.tabId,
+          savedWindowId: ref.windowId,
+          candidateCount: matches.length,
+          inventoryTruncated: inventory.truncated,
+        },
+      },
+    );
+  }
+
+  const match = matches[0]!;
+  return { windowId: match.windowId, tabId: match.tabId };
+}
+
+export async function listMacOsBrowserTabs(
+  product: MacOsBrowserProduct,
+  timeoutMs = DEFAULT_NATIVE_TIMEOUT_MS,
+): Promise<MacOsBrowserTabInventory> {
+  const browser = browserDefinition(product);
+  const raw = await runBrowserAutomationText(
+    { action: 'list_tabs', product },
+    listTabsScript(browser),
+    [],
+    timeoutMs,
+  );
+  return parseTabInventory(product, raw);
+}
+
 export async function readMacOsBrowserOwnedTabMetadata(
   product: MacOsBrowserProduct,
   ref: MacOsBrowserTabRef,
   timeoutMs = DEFAULT_NATIVE_TIMEOUT_MS,
 ): Promise<MacOsBrowserMetadata> {
   const browser = browserDefinition(product);
+  const resolvedRef = await resolveCurrentMacOsBrowserTabRef(product, ref, timeoutMs);
   return parseMetadata(product, await runBrowserAutomationText(
-    { action: 'metadata', product, ref },
-    targetMetadataScript(browser, ref),
+    { action: 'metadata', product, ref: resolvedRef },
+    targetMetadataScript(browser, resolvedRef),
     [],
     timeoutMs,
   ));
@@ -811,13 +1303,33 @@ export async function activateMacOsBrowserOwnedTab(
   timeoutMs = DEFAULT_NATIVE_TIMEOUT_MS,
 ): Promise<MacOsBrowserMetadata> {
   const browser = browserDefinition(product);
+  const resolvedRef = await resolveCurrentMacOsBrowserTabRef(product, ref, timeoutMs);
   await runBrowserAutomationText(
-    { action: 'activate', product, ref },
-    activateTargetTabScript(browser, ref),
+    { action: 'activate', product, ref: resolvedRef },
+    activateTargetTabScript(browser, resolvedRef),
     [],
     timeoutMs,
   );
-  return readMacOsBrowserOwnedTabMetadata(product, ref, timeoutMs);
+  const metadata = await readMacOsBrowserOwnedTabMetadata(product, resolvedRef, timeoutMs);
+  if (metadata.tabId !== resolvedRef.tabId || metadata.active !== true) {
+    throw new AssistantPluginError(
+      'PLUGIN_BROWSER_NATIVE_ACTIVATION_POSTCONDITION_FAILED',
+      `${browser.appName} did not prove that the exact requested tab became active.`,
+      {
+        retryable: true,
+        details: {
+          browserProduct: product,
+          requestedTabId: resolvedRef.tabId,
+          resolvedWindowId: resolvedRef.windowId,
+          observedWindowId: metadata.windowId,
+          observedTabId: metadata.tabId,
+          observedActive: metadata.active,
+          observedFrontmost: metadata.frontmost,
+        },
+      },
+    );
+  }
+  return metadata;
 }
 
 export function createMacOsBrowserPage(attachment: MacOsBrowserAttachment, timeoutMs?: number): MacOsAppleEventsPage {
@@ -839,10 +1351,12 @@ export async function createMacOsBrowserOwnedPage(
   const parts = raw.split(RECORD_SEPARATOR);
   if (parts.length < 2) throw new Error(`Browser scripting returned incomplete owned-tab metadata for ${browser.appName}.`);
   const ref = { windowId: parseBrowserId(parts[0] ?? '', 'window id'), tabId: parseBrowserId(parts[1] ?? '', 'tab id') };
-  return new MacOsAppleEventsPage({
+  const page = new MacOsAppleEventsPage({
     ...attachment,
     metadata: { ...attachment.metadata, url, title: '', windowId: ref.windowId, tabId: ref.tabId, active: false },
   }, timeoutMs, ref);
+  rememberMacOsBrowserPageHandle(attachment.metadata.product, ref, page);
+  return page;
 }
 
 export async function reattachMacOsBrowserOwnedPage(
@@ -850,12 +1364,26 @@ export async function reattachMacOsBrowserOwnedPage(
   ref: MacOsBrowserTabRef,
   timeoutMs = DEFAULT_NATIVE_TIMEOUT_MS,
 ): Promise<{ page: MacOsAppleEventsPage; attachment: MacOsBrowserAttachment }> {
+  const cacheKey = nativePageHandleKey(product, ref);
+  const cached = warmNativePageHandles.get(cacheKey);
+  if (cached) {
+    cached.updateTimeout(timeoutMs);
+    // Refresh insertion order so bounded eviction behaves as a small LRU.
+    warmNativePageHandles.delete(cacheKey);
+    warmNativePageHandles.set(cacheKey, cached);
+    return { page: cached, attachment: cached.attachmentSnapshot() };
+  }
   const metadata = await readMacOsBrowserOwnedTabMetadata(product, ref, timeoutMs);
   const attachment: MacOsBrowserAttachment = {
     metadata,
     attempts: [{ product, appName: metadata.appName, bundleId: metadata.bundleId, status: 'selected', frontmost: metadata.frontmost }],
   };
-  return { page: new MacOsAppleEventsPage(attachment, timeoutMs, ref), attachment };
+  const resolvedRef = metadata.windowId && metadata.tabId
+    ? { windowId: metadata.windowId, tabId: metadata.tabId }
+    : ref;
+  const page = new MacOsAppleEventsPage(attachment, timeoutMs, resolvedRef);
+  rememberMacOsBrowserPageHandle(product, resolvedRef, page);
+  return { page, attachment };
 }
 
 export async function closeMacOsBrowserOwnedTab(
@@ -864,10 +1392,15 @@ export async function closeMacOsBrowserOwnedTab(
   timeoutMs = DEFAULT_NATIVE_TIMEOUT_MS,
 ): Promise<void> {
   const browser = browserDefinition(product);
-  await runBrowserAutomationText(
-    { action: 'close_tab', product, ref },
-    closeOwnedTabScript(browser, ref),
-    [],
-    timeoutMs,
-  );
+  try {
+    const resolvedRef = await resolveCurrentMacOsBrowserTabRef(product, ref, timeoutMs);
+    await runBrowserAutomationText(
+      { action: 'close_tab', product, ref: resolvedRef },
+      closeOwnedTabScript(browser, resolvedRef),
+      [],
+      timeoutMs,
+    );
+  } finally {
+    invalidateMacOsBrowserPageHandle(product, ref);
+  }
 }