@moretea-labs/forge 1.7.0 → 1.7.1

package/src/runtime/plugins/browser-handoff-host.ts

@@ -1,8 +1,8 @@
 import { createRequire } from 'module';
-import { existsSync, rmSync } from 'fs';
+import { rmSync } from 'fs';
 import { basename } from 'path';
 import { spawnSync } from 'child_process';
-import { readJsonFile, writeJsonAtomic } from '../shared/json-files';
+import { readJsonFile } from '../shared/json-files';
 import {
   interactionCommandPath,
   patchInteractionSession,
@@ -100,19 +100,7 @@ async function runNativeHandoff(specPath: string, spec: BrowserHandoffLaunchSpec
         removeInteractionCommand(spec.repoRoot, 'browser', spec.interactionId, 'resume');
         metadata = await readMacOsBrowserOwnedTabMetadata(native.product, native.ref, spec.defaultTimeoutMs);
         assertHttpUrl(metadata.url);
-        const existing = existsSync(spec.sessionPath)
-          ? readJsonFile<Record<string, unknown>>(spec.sessionPath, {})
-          : {};
-        const timestamp = new Date().toISOString();
         const result = { url: metadata.url, title: metadata.title };
-        writeJsonAtomic(spec.sessionPath, {
-          ...existing,
-          schemaVersion: 1,
-          sessionId: spec.sessionId,
-          ...result,
-          createdAt: typeof existing.createdAt === 'string' ? existing.createdAt : timestamp,
-          updatedAt: timestamp,
-        });
         terminalOutcome = { status: 'completed', result };
         patchInteractionSession(spec.repoRoot, 'browser', spec.interactionId, { status: 'closing', result });
         break;
@@ -239,18 +227,7 @@ async function main(): Promise<void> {
       if (resume) {
         removeInteractionCommand(spec.repoRoot, 'browser', spec.interactionId, 'resume');
         assertHttpUrl(page.url());
-        const existing = existsSync(spec.sessionPath)
-          ? readJsonFile<Record<string, unknown>>(spec.sessionPath, {})
-          : {};
-        const timestamp = new Date().toISOString();
         const result = { url: page.url(), title: await page.title() };
-        writeJsonAtomic(spec.sessionPath, {
-          schemaVersion: 1,
-          sessionId: spec.sessionId,
-          ...result,
-          createdAt: typeof existing.createdAt === 'string' ? existing.createdAt : timestamp,
-          updatedAt: timestamp,
-        });
         terminalOutcome = { status: 'completed', result };
         patchInteractionSession(spec.repoRoot, 'browser', spec.interactionId, { status: 'closing', result });
         break;

package/src/runtime/plugins/browser-handoff.ts

@@ -32,7 +32,6 @@ export interface BrowserHandoffLaunchSpec {
   repoRoot: string;
   interactionId: string;
   sessionId: string;
-  sessionPath: string;
   url: string;
   profileDir: string;
   selectedProfilePath: string;
@@ -50,7 +49,6 @@ export interface BrowserHandoffStartInput {
   requestId: string;
   jobId?: string;
   sessionId: string;
-  sessionPath: string;
   url: string;
   profileDir: string;
   selectedProfilePath: string;
@@ -407,7 +405,6 @@ export async function startBrowserHandoff(input: BrowserHandoffStartInput): Prom
     repoRoot: input.repoRoot,
     interactionId,
     sessionId: input.sessionId,
-    sessionPath: input.sessionPath,
     url: input.url,
     profileDir: input.profileDir,
     selectedProfilePath: input.selectedProfilePath,
@@ -443,6 +440,24 @@ export function resumeBrowserHandoff(repoRoot: string, interactionId: string, re
   return current;
 }
 
+export async function resumeBrowserHandoffAndWait(
+  repoRoot: string,
+  interactionId: string,
+  requestedBy: string,
+  timeoutMs = 5_000,
+): Promise<InteractionSessionRecord> {
+  const initial = resumeBrowserHandoff(repoRoot, interactionId, requestedBy);
+  if (!isInteractionSessionActive(initial.status)) return initial;
+  const deadline = Date.now() + Math.max(0, Math.trunc(timeoutMs));
+  let latest = initial;
+  while (Date.now() < deadline) {
+    await hooks.wait(STARTUP_POLL_MS);
+    latest = getBrowserHandoff(repoRoot, interactionId);
+    if (!isInteractionSessionActive(latest.status)) return latest;
+  }
+  return latest;
+}
+
 export function cancelBrowserHandoff(repoRoot: string, interactionId: string, requestedBy: string): InteractionSessionRecord {
   const current = getBrowserHandoff(repoRoot, interactionId);
   if (!isInteractionSessionActive(current.status) || current.status === 'closing') return current;

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

@@ -9,12 +9,13 @@ import {
   type BrowserAutomationTrustedInput,
 } from './browser-automation-service';
 import { AssistantPluginError } from './errors';
+import type { BrowserNativeAttachAttempt, BrowserNativeProduct } from './browser-session-types';
 
 const RECORD_SEPARATOR = String.fromCharCode(30);
 const DEFAULT_NATIVE_TIMEOUT_MS = 5_000;
 const MAX_NATIVE_OUTPUT_BYTES = 1_048_576;
 
-export type MacOsBrowserProduct = 'chrome' | 'vivaldi';
+export type MacOsBrowserProduct = BrowserNativeProduct;
 
 interface MacOsBrowserDefinition {
   product: MacOsBrowserProduct;
@@ -29,6 +30,20 @@ export interface MacOsBrowserTabRef {
   tabId: string;
 }
 
+export interface MacOsBrowserCreateTabNavigationProvenance {
+  provenanceVersion: 1;
+  requestedUrl: string;
+  assignmentAccepted: true;
+  acceptedBy?: string;
+  observedUrlAfterAssignment?: string;
+}
+
+export interface MacOsBrowserCreateTabEvidence {
+  ref: MacOsBrowserTabRef;
+  refSource: 'structured' | 'legacy_value';
+  navigation?: MacOsBrowserCreateTabNavigationProvenance;
+}
+
 export interface MacOsBrowserMetadata {
   product: MacOsBrowserProduct;
   appName: string;
@@ -57,14 +72,7 @@ export interface MacOsBrowserTabInventory {
   truncated: boolean;
 }
 
-export interface MacOsBrowserAttachAttempt {
-  product: MacOsBrowserProduct;
-  appName: string;
-  bundleId: string;
-  status: 'selected' | 'available' | 'not_installed' | 'not_running' | 'unavailable';
-  frontmost?: boolean;
-  error?: string;
-}
+export type MacOsBrowserAttachAttempt = BrowserNativeAttachAttempt;
 
 export interface MacOsBrowserAttachment {
   metadata: MacOsBrowserMetadata;
@@ -132,6 +140,87 @@ const defaultRuntimeHooks: MacOsBrowserRuntimeHooks = {
   },
 };
 
+export function parseMacOsBrowserCreateTabBrokerResult(result: Record<string, unknown>): MacOsBrowserCreateTabEvidence {
+  const structuredRef = result.ref;
+  let ref: MacOsBrowserTabRef;
+  let refSource: MacOsBrowserCreateTabEvidence['refSource'];
+  if (structuredRef !== undefined) {
+    if (!structuredRef || typeof structuredRef !== 'object' || Array.isArray(structuredRef)) {
+      throw new AssistantPluginError('PLUGIN_MACOS_CAPABILITY_BROKER_PROTOCOL_ERROR', 'Stable Forge macOS capability broker returned an invalid create-tab ref.', { retryable: true });
+    }
+    const record = structuredRef as Record<string, unknown>;
+    if (typeof record.windowId !== 'string' || !record.windowId.trim() || typeof record.tabId !== 'string' || !record.tabId.trim()) {
+      throw new AssistantPluginError('PLUGIN_MACOS_CAPABILITY_BROKER_PROTOCOL_ERROR', 'Stable Forge macOS capability broker returned an incomplete create-tab ref.', { retryable: true });
+    }
+    ref = { windowId: record.windowId, tabId: record.tabId };
+    refSource = 'structured';
+    if (typeof result.value === 'string') {
+      const legacyParts = result.value.split(RECORD_SEPARATOR);
+      if (legacyParts.length >= 2) {
+        const legacyRef = {
+          windowId: parseBrowserId(legacyParts[0] ?? '', 'window id'),
+          tabId: parseBrowserId(legacyParts[1] ?? '', 'tab id'),
+        };
+        if (legacyRef.windowId !== ref.windowId || legacyRef.tabId !== ref.tabId) {
+          throw new AssistantPluginError('PLUGIN_MACOS_CAPABILITY_BROKER_PROTOCOL_ERROR', 'Stable Forge macOS capability broker returned conflicting structured and legacy create-tab refs.', { retryable: true });
+        }
+      }
+    }
+  } else {
+    if (typeof result.value !== 'string') {
+      throw new AssistantPluginError('PLUGIN_MACOS_CAPABILITY_BROKER_PROTOCOL_ERROR', 'Stable Forge macOS capability broker returned no create-tab ref.', { retryable: true });
+    }
+    const parts = result.value.split(RECORD_SEPARATOR);
+    if (parts.length < 2) throw new AssistantPluginError('PLUGIN_MACOS_CAPABILITY_BROKER_PROTOCOL_ERROR', 'Stable Forge macOS capability broker returned incomplete legacy create-tab metadata.', { retryable: true });
+    ref = { windowId: parseBrowserId(parts[0] ?? '', 'window id'), tabId: parseBrowserId(parts[1] ?? '', 'tab id') };
+    refSource = 'legacy_value';
+  }
+
+  const navigationValue = result.navigation;
+  if (navigationValue === undefined) return { ref, refSource };
+  if (!navigationValue || typeof navigationValue !== 'object' || Array.isArray(navigationValue)) {
+    throw new AssistantPluginError('PLUGIN_MACOS_CAPABILITY_BROKER_PROTOCOL_ERROR', 'Stable Forge macOS capability broker returned invalid create-tab navigation provenance.', { retryable: true });
+  }
+  const navigation = navigationValue as Record<string, unknown>;
+  if (navigation.provenanceVersion !== 1
+    || typeof navigation.requestedUrl !== 'string'
+    || navigation.assignmentAccepted !== true) {
+    throw new AssistantPluginError('PLUGIN_MACOS_CAPABILITY_BROKER_PROTOCOL_ERROR', 'Stable Forge macOS capability broker returned incomplete create-tab navigation provenance.', { retryable: true });
+  }
+  if (navigation.acceptedBy !== undefined && typeof navigation.acceptedBy !== 'string') {
+    throw new AssistantPluginError('PLUGIN_MACOS_CAPABILITY_BROKER_PROTOCOL_ERROR', 'Stable Forge macOS capability broker returned invalid create-tab acceptedBy provenance.', { retryable: true });
+  }
+  if (navigation.observedUrlAfterAssignment !== undefined && typeof navigation.observedUrlAfterAssignment !== 'string') {
+    throw new AssistantPluginError('PLUGIN_MACOS_CAPABILITY_BROKER_PROTOCOL_ERROR', 'Stable Forge macOS capability broker returned invalid create-tab observed URL provenance.', { retryable: true });
+  }
+  const acceptedBy = typeof navigation.acceptedBy === 'string' ? navigation.acceptedBy : undefined;
+  const observedUrlAfterAssignment = typeof navigation.observedUrlAfterAssignment === 'string' ? navigation.observedUrlAfterAssignment : undefined;
+  return {
+    ref,
+    refSource,
+    navigation: {
+      provenanceVersion: 1,
+      requestedUrl: navigation.requestedUrl,
+      assignmentAccepted: true,
+      ...(acceptedBy ? { acceptedBy } : {}),
+      ...(observedUrlAfterAssignment ? { observedUrlAfterAssignment } : {}),
+    },
+  };
+}
+
+async function runCreateTabAutomation(
+  request: Extract<BrowserAutomationBrokerAction, { action: 'create_tab' }>,
+  testScript: string,
+  testArgs: string[],
+  timeoutMs: number,
+): Promise<MacOsBrowserCreateTabEvidence> {
+  if (runtimeHooks.runAppleScript) {
+    const value = await runtimeHooks.runAppleScript(testScript, testArgs, timeoutMs);
+    return parseMacOsBrowserCreateTabBrokerResult({ value });
+  }
+  return parseMacOsBrowserCreateTabBrokerResult(await callBrowserAutomationBroker(request, timeoutMs));
+}
+
 async function runBrowserAutomationText(
   request: BrowserAutomationBrokerAction,
   testScript: string,
@@ -673,12 +762,18 @@ export class MacOsAppleEventsPage {
   private readonly browser: MacOsBrowserDefinition;
   private timeoutMs: number;
   private targetRef?: MacOsBrowserTabRef;
+  private readonly createTabEvidence?: MacOsBrowserCreateTabEvidence;
 
-  constructor(attachment: MacOsBrowserAttachment, timeoutMs = DEFAULT_NATIVE_TIMEOUT_MS, targetRef?: MacOsBrowserTabRef) {
+  constructor(attachment: MacOsBrowserAttachment, timeoutMs = DEFAULT_NATIVE_TIMEOUT_MS, targetRef?: MacOsBrowserTabRef, createTabEvidence?: MacOsBrowserCreateTabEvidence) {
     this.metadata = { ...attachment.metadata, ...(targetRef ? { windowId: targetRef.windowId, tabId: targetRef.tabId } : {}) };
     this.browser = browserDefinition(attachment.metadata.product);
     this.timeoutMs = timeoutMs;
     this.targetRef = targetRef;
+    this.createTabEvidence = createTabEvidence ? {
+      ...createTabEvidence,
+      ref: { ...createTabEvidence.ref },
+      ...(createTabEvidence.navigation ? { navigation: { ...createTabEvidence.navigation } } : {}),
+    } : undefined;
   }
 
   private async runAutomation(
@@ -741,6 +836,14 @@ export class MacOsAppleEventsPage {
     return this.targetRef ? { ...this.targetRef } : undefined;
   }
 
+  creationEvidence(): MacOsBrowserCreateTabEvidence | undefined {
+    return this.createTabEvidence ? {
+      ...this.createTabEvidence,
+      ref: { ...this.createTabEvidence.ref },
+      ...(this.createTabEvidence.navigation ? { navigation: { ...this.createTabEvidence.navigation } } : {}),
+    } : undefined;
+  }
+
   updateTimeout(timeoutMs: number): void {
     if (Number.isFinite(timeoutMs) && timeoutMs > 0) this.timeoutMs = Math.trunc(timeoutMs);
   }
@@ -1195,7 +1298,11 @@ export class MacOsAppleEventsPage {
       }
       await new Promise((resolve) => setTimeout(resolve, 100));
     }
-    throw new Error(`Timeout waiting for browser load state ${state}.`);
+    throw new AssistantPluginError(
+      'PLUGIN_BROWSER_LOAD_STATE_TIMEOUT',
+      `Timed out waiting for native browser load state ${state}.`,
+      { retryable: true, details: { state, timeoutMs: timeout, requireHttpUrl } },
+    );
   }
 
   locator(_selector: string): { screenshot: (options?: Record<string, unknown>) => Promise<Buffer> } {
@@ -1342,19 +1449,17 @@ export async function createMacOsBrowserOwnedPage(
   timeoutMs = DEFAULT_NATIVE_TIMEOUT_MS,
 ): Promise<MacOsAppleEventsPage> {
   const browser = browserDefinition(attachment.metadata.product);
-  const raw = await runBrowserAutomationText(
+  const creationEvidence = await runCreateTabAutomation(
     { action: 'create_tab', product: attachment.metadata.product, url },
     createOwnedTabScript(browser),
     [url],
     timeoutMs,
   );
-  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') };
+  const ref = creationEvidence.ref;
   const page = new MacOsAppleEventsPage({
     ...attachment,
     metadata: { ...attachment.metadata, url, title: '', windowId: ref.windowId, tabId: ref.tabId, active: false },
-  }, timeoutMs, ref);
+  }, timeoutMs, ref, creationEvidence);
   rememberMacOsBrowserPageHandle(attachment.metadata.product, ref, page);
   return page;
 }