@moretea-labs/forge 1.6.0 → 1.7.1

package/src/runtime/plugins/browser-native-session-service.ts

@@ -0,0 +1,222 @@
+import { AssistantPluginError } from './errors';
+import {
+  closeMacOsBrowserOwnedTab,
+  listMacOsBrowserTabs,
+  macOsBrowserPageHandleStale,
+  readMacOsBrowserOwnedTabMetadata,
+  type MacOsBrowserProduct,
+} from './browser-macos-bridge';
+import { listSavedBrowserSessions, removeBrowserSession } from './browser-session-store';
+import type { BrowserSessionInventoryItem, BrowserSessionState } from './browser-session-types';
+
+export interface NativeOwnedSessionInspection {
+  items: Map<string, BrowserSessionInventoryItem>;
+  liveCount: number;
+  deadCount: number;
+  unverifiedCount: number;
+  prunedCount: number;
+  closedInvalidCount: number;
+  failedCleanupCount: number;
+}
+
+export function nativeTabInventoryUnsupported(error: unknown): boolean {
+  if (error instanceof AssistantPluginError && error.code === 'BROWSER_AUTOMATION_ACTION_UNSUPPORTED') return true;
+  const message = error instanceof Error ? error.message : String(error ?? '');
+  return /\bBROWSER_AUTOMATION_ACTION_UNSUPPORTED\b/.test(message);
+}
+
+function isDiscardableNativeOwnedTabUrl(url: string): boolean {
+  const normalized = url.trim().toLowerCase();
+  return normalized === ''
+    || normalized === 'about:blank'
+    || normalized === 'chrome://newtab/'
+    || normalized === 'chrome://new-tab-page/'
+    || normalized === 'vivaldi://newtab/'
+    || normalized === 'vivaldi://startpage/';
+}
+
+/**
+ * Native tab liveness/cleanup belongs to one service so the Browser adapter does
+ * not reinterpret stable native identity or prune policy action-by-action.
+ */
+export async function inspectNativeOwnedSessions(input: {
+  repoRoot: string;
+  savedSessions: BrowserSessionState[];
+  timeoutMs: number;
+  pruneDead?: boolean;
+}): Promise<NativeOwnedSessionInspection> {
+  const { repoRoot, savedSessions, timeoutMs } = input;
+  const items = new Map<string, BrowserSessionInventoryItem>();
+  const inventories = new Map<MacOsBrowserProduct, Awaited<ReturnType<typeof listMacOsBrowserTabs>> | Error>();
+  const groups = new Map<string, BrowserSessionState[]>();
+  let liveCount = 0;
+  let deadCount = 0;
+  let unverifiedCount = 0;
+  let prunedCount = 0;
+  let closedInvalidCount = 0;
+  let failedCleanupCount = 0;
+
+  for (const session of savedSessions) {
+    const browser = session.browser;
+    const tab = browser?.tab;
+    const product = browser?.browserProduct;
+    if (browser?.provider !== 'macos-apple-events' || tab?.ownership !== 'plugin_owned' || !product || !tab.windowId || !tab.tabId) continue;
+    const key = `${product}:${tab.windowId}:${tab.tabId}`;
+    const group = groups.get(key) ?? [];
+    group.push(session);
+    groups.set(key, group);
+  }
+
+  for (const group of groups.values()) {
+    const canonical = group.reduce((latest, session) => session.updatedAt > latest.updatedAt ? session : latest);
+    const browser = canonical.browser!;
+    const tab = browser.tab!;
+    const product = browser.browserProduct!;
+    let inventory = inventories.get(product);
+    if (!inventory) {
+      try {
+        inventory = await listMacOsBrowserTabs(product, timeoutMs);
+      } catch (error) {
+        inventory = error instanceof Error ? error : new Error(String(error));
+      }
+      inventories.set(product, inventory);
+    }
+    if (inventory instanceof Error) {
+      if (!nativeTabInventoryUnsupported(inventory)) {
+        for (const session of group) items.set(session.sessionId, { session, liveness: 'unverified', evidence: 'native_inventory_unavailable', cleanupError: inventory.message });
+        unverifiedCount += group.length;
+        continue;
+      }
+
+      const ref = { windowId: tab.windowId!, tabId: tab.tabId! };
+      let metadata: Awaited<ReturnType<typeof readMacOsBrowserOwnedTabMetadata>>;
+      try {
+        metadata = await readMacOsBrowserOwnedTabMetadata(product, ref, timeoutMs);
+      } catch (metadataError) {
+        if (macOsBrowserPageHandleStale(metadataError)) {
+          const pruned = input.pruneDead === true;
+          if (pruned) {
+            for (const session of group) removeBrowserSession(repoRoot, session.sessionId);
+            prunedCount += group.length;
+          }
+          for (const session of group) items.set(session.sessionId, { session, liveness: 'dead', evidence: 'native_tab_missing', pruned });
+          deadCount += group.length;
+        } else {
+          const cleanupError = metadataError instanceof Error ? metadataError.message : String(metadataError);
+          for (const session of group) items.set(session.sessionId, { session, liveness: 'unverified', evidence: 'native_inventory_unavailable', cleanupError });
+          unverifiedCount += group.length;
+        }
+        continue;
+      }
+
+      if (isDiscardableNativeOwnedTabUrl(metadata.url)) {
+        deadCount += group.length;
+        if (input.pruneDead === true) {
+          try {
+            await closeMacOsBrowserOwnedTab(product, ref, timeoutMs);
+            for (const session of group) removeBrowserSession(repoRoot, session.sessionId);
+            prunedCount += group.length;
+            closedInvalidCount += 1;
+            for (const session of group) items.set(session.sessionId, { session, liveness: 'dead', evidence: 'native_tab_invalid_closed', pruned: true });
+          } catch (error) {
+            failedCleanupCount += 1;
+            const cleanupError = error instanceof Error ? error.message : String(error);
+            for (const session of group) items.set(session.sessionId, { session, liveness: 'dead', evidence: 'native_tab_invalid_close_failed', cleanupError });
+          }
+        } else {
+          for (const session of group) items.set(session.sessionId, { session, liveness: 'dead', evidence: 'native_tab_invalid' });
+        }
+      } else {
+        for (const session of group) items.set(session.sessionId, { session, liveness: 'live', evidence: 'native_tab_live' });
+        liveCount += group.length;
+      }
+      continue;
+    }
+
+    const live = inventory.tabs.find((entry) => entry.windowId === tab.windowId && entry.tabId === tab.tabId);
+    if (!live) {
+      const pruned = input.pruneDead === true;
+      if (pruned) {
+        for (const session of group) removeBrowserSession(repoRoot, session.sessionId);
+        prunedCount += group.length;
+      }
+      for (const session of group) items.set(session.sessionId, { session, liveness: 'dead', evidence: 'native_tab_missing', pruned });
+      deadCount += group.length;
+      continue;
+    }
+
+    if (isDiscardableNativeOwnedTabUrl(live.url)) {
+      deadCount += group.length;
+      if (input.pruneDead === true) {
+        try {
+          await closeMacOsBrowserOwnedTab(product, { windowId: tab.windowId!, tabId: tab.tabId! }, timeoutMs);
+          for (const session of group) removeBrowserSession(repoRoot, session.sessionId);
+          prunedCount += group.length;
+          closedInvalidCount += 1;
+          for (const session of group) items.set(session.sessionId, { session, liveness: 'dead', evidence: 'native_tab_invalid_closed', pruned: true });
+        } catch (error) {
+          failedCleanupCount += 1;
+          const cleanupError = error instanceof Error ? error.message : String(error);
+          for (const session of group) items.set(session.sessionId, { session, liveness: 'dead', evidence: 'native_tab_invalid_close_failed', cleanupError });
+        }
+      } else {
+        for (const session of group) items.set(session.sessionId, { session, liveness: 'dead', evidence: 'native_tab_invalid' });
+      }
+      continue;
+    }
+
+    for (const session of group) items.set(session.sessionId, { session, liveness: 'live', evidence: 'native_tab_live' });
+    liveCount += group.length;
+  }
+
+  return { items, liveCount, deadCount, unverifiedCount, prunedCount, closedInvalidCount, failedCleanupCount };
+}
+
+export async function closeTrackedNativeOwnedSession(
+  session: BrowserSessionState,
+  timeoutMs: number,
+): Promise<{ resourceClosed: boolean; resourceAlreadyMissing: boolean }> {
+  const browser = session.browser;
+  const tab = browser?.tab;
+  if (browser?.provider !== 'macos-apple-events' || tab?.ownership !== 'plugin_owned') {
+    return { resourceClosed: false, resourceAlreadyMissing: false };
+  }
+  if (!browser.browserProduct || !tab.windowId || !tab.tabId) {
+    throw new AssistantPluginError('PLUGIN_BROWSER_NATIVE_OWNERSHIP_MISSING', 'Tracked plugin-owned native tab is missing stable browser identity; retaining session metadata instead of orphaning the tab.', {
+      retryable: false, details: { sessionId: session.sessionId, browserProduct: browser.browserProduct, windowId: tab.windowId, tabId: tab.tabId },
+    });
+  }
+  const ref = { windowId: tab.windowId, tabId: tab.tabId };
+  let inventory: Awaited<ReturnType<typeof listMacOsBrowserTabs>> | undefined;
+  try {
+    inventory = await listMacOsBrowserTabs(browser.browserProduct, timeoutMs);
+  } catch (error) {
+    if (!nativeTabInventoryUnsupported(error)) throw error;
+    try {
+      await readMacOsBrowserOwnedTabMetadata(browser.browserProduct, ref, timeoutMs);
+    } catch (metadataError) {
+      if (macOsBrowserPageHandleStale(metadataError)) return { resourceClosed: false, resourceAlreadyMissing: true };
+      throw metadataError;
+    }
+  }
+  if (inventory && !inventory.tabs.some((entry) => entry.windowId === tab.windowId && entry.tabId === tab.tabId)) {
+    return { resourceClosed: false, resourceAlreadyMissing: true };
+  }
+  await closeMacOsBrowserOwnedTab(browser.browserProduct, ref, timeoutMs);
+  return { resourceClosed: true, resourceAlreadyMissing: false };
+}
+
+export function nativeOwnedAliasSessionIds(repoRoot: string, session: BrowserSessionState): string[] {
+  const browser = session.browser;
+  const tab = browser?.tab;
+  if (browser?.provider !== 'macos-apple-events' || tab?.ownership !== 'plugin_owned' || !browser.browserProduct || !tab.windowId || !tab.tabId) {
+    return [session.sessionId];
+  }
+  return listSavedBrowserSessions(repoRoot)
+    .filter((candidate) => candidate.browser?.provider === 'macos-apple-events'
+      && candidate.browser.browserProduct === browser.browserProduct
+      && candidate.browser.tab?.ownership === 'plugin_owned'
+      && candidate.browser.tab.windowId === tab.windowId
+      && candidate.browser.tab.tabId === tab.tabId)
+    .map((candidate) => candidate.sessionId);
+}

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

@@ -1,9 +1,10 @@
 import { spawn } from 'child_process';
-import { accessSync, constants, existsSync } from 'fs';
-import { delimiter, dirname, isAbsolute, join, resolve } from 'path';
+import { existsSync } from 'fs';
+import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import type { AssistantPluginActionExecutionInput } from './types';
 import { AssistantPluginError } from './errors';
+import { resolveTrustedNodeExecutable } from '../shared/trusted-node-executable';
 
 const BRIDGE_SCHEMA_VERSION = 1;
 const MAX_REQUEST_BYTES = 1_048_576;
@@ -43,43 +44,14 @@ interface BridgeFailure {
 
 type BridgeResponse = BridgeSuccess | BridgeFailure;
 
-function isExecutable(path: string): boolean {
-  try {
-    accessSync(path, constants.X_OK);
-    return existsSync(path);
-  } catch {
-    return false;
-  }
-}
-
-function pathCandidates(env: NodeJS.ProcessEnv): string[] {
-  const candidates = [
-    env.FORGE_NODE_EXECUTABLE,
-    env.VOLTA_HOME ? join(env.VOLTA_HOME, 'bin', 'node') : undefined,
-    '/opt/homebrew/bin/node',
-    '/usr/local/bin/node',
-    '/usr/bin/node',
-  ];
-  for (const entry of (env.PATH ?? '').split(delimiter)) {
-    if (entry.trim()) candidates.push(join(entry, process.platform === 'win32' ? 'node.exe' : 'node'));
-  }
-  return candidates.filter((value): value is string => Boolean(value));
-}
-
 export function resolveBrowserBridgeNodeExecutable(env: NodeJS.ProcessEnv = process.env): string {
-  if (env.FORGE_NODE_EXECUTABLE) {
-    const configured = isAbsolute(env.FORGE_NODE_EXECUTABLE)
-      ? env.FORGE_NODE_EXECUTABLE
-      : resolve(env.FORGE_NODE_EXECUTABLE);
-    if (isExecutable(configured)) return configured;
+  const resolution = resolveTrustedNodeExecutable(env);
+  if (resolution.executable) return resolution.executable;
+  if (resolution.configuredInvalid) {
     throw new AssistantPluginError('PLUGIN_BROWSER_NODE_UNAVAILABLE', 'The configured Browser bridge Node executable is not executable.', {
       retryable: false,
     });
   }
-  for (const candidate of pathCandidates(env)) {
-    const absolute = isAbsolute(candidate) ? candidate : resolve(candidate);
-    if (isExecutable(absolute)) return absolute;
-  }
   throw new AssistantPluginError('PLUGIN_BROWSER_NODE_UNAVAILABLE', 'Browser attach operations require a trusted Node executable, but none was found.', {
     retryable: false,
   });

package/src/runtime/plugins/browser-provider-registry.ts

@@ -0,0 +1,109 @@
+import { AssistantPluginError } from './errors';
+import {
+  providerSupports,
+  type BrowserForegroundRequirement,
+  type BrowserProviderCapabilities,
+  type BrowserProviderCapability,
+} from './browser-runtime-contract';
+
+export interface BrowserRuntimeProvider<TInput, TResult> extends BrowserProviderCapabilities {
+  /** Lower values are preferred when multiple providers satisfy the same capability contract. */
+  priority: number;
+  /** Availability is decided before execution; ordinary provider failures are never fallback signals. */
+  supportsInput(input: TInput): boolean;
+  execute(input: TInput): Promise<TResult>;
+  /** Runs only after an explicit stale/restart/configuration boundary. */
+  revalidate?: () => Promise<void> | void;
+}
+
+interface BrowserProviderState<TInput, TResult> {
+  provider: BrowserRuntimeProvider<TInput, TResult>;
+  generation: number;
+  invalidatedReason?: string;
+}
+
+export interface BrowserProviderSelection<TInput, TResult> {
+  provider: BrowserRuntimeProvider<TInput, TResult>;
+  generation: number;
+}
+
+/**
+ * A typed pre-action rejection. Runtime may select another provider because this proves the action
+ * was not attempted. Arbitrary provider errors are intentionally not mapped to this signal.
+ */
+export class BrowserProviderUnavailableBeforeActionError extends Error {
+  readonly providerId: string;
+  readonly reason: string;
+
+  constructor(providerId: string, reason: string) {
+    super(`${providerId} unavailable before action: ${reason}`);
+    this.name = 'BrowserProviderUnavailableBeforeActionError';
+    this.providerId = providerId;
+    this.reason = reason;
+  }
+}
+
+function foregroundCompatible(
+  provider: BrowserProviderCapabilities,
+  requested: BrowserForegroundRequirement,
+): boolean {
+  // Background-safe providers may execute explicit foreground transactions; foreground-only
+  // providers may not satisfy a background-safe transaction.
+  return requested === 'explicit_required' || provider.foreground === 'none';
+}
+
+export class BrowserProviderRegistry<TInput, TResult> {
+  private readonly providers = new Map<string, BrowserProviderState<TInput, TResult>>();
+
+  register(provider: BrowserRuntimeProvider<TInput, TResult>): void {
+    const current = this.providers.get(provider.providerId);
+    if (current) {
+      // Refresh call-local closures without discarding the warm provider generation.
+      current.provider = provider;
+      return;
+    }
+    this.providers.set(provider.providerId, { provider, generation: 1 });
+  }
+
+  invalidate(providerId: string, reason: string): void {
+    const state = this.providers.get(providerId);
+    if (state) state.invalidatedReason = reason;
+  }
+
+  invalidateAll(reason: string): void {
+    for (const state of this.providers.values()) state.invalidatedReason = reason;
+  }
+
+  private async prepare(state: BrowserProviderState<TInput, TResult>): Promise<void> {
+    if (!state.invalidatedReason) return;
+    await state.provider.revalidate?.();
+    state.invalidatedReason = undefined;
+    state.generation += 1;
+  }
+
+  async select(options: {
+    input: TInput;
+    requiredCapabilities: readonly BrowserProviderCapability[];
+    foreground: BrowserForegroundRequirement;
+    excludedProviderIds?: ReadonlySet<string>;
+  }): Promise<BrowserProviderSelection<TInput, TResult>> {
+    const candidates = [...this.providers.values()]
+      .filter(({ provider }) => !options.excludedProviderIds?.has(provider.providerId))
+      .filter(({ provider }) => provider.supportsInput(options.input))
+      .filter(({ provider }) => providerSupports(provider, options.requiredCapabilities))
+      .filter(({ provider }) => foregroundCompatible(provider, options.foreground))
+      .sort((left, right) => left.provider.priority - right.provider.priority
+        || left.provider.providerId.localeCompare(right.provider.providerId));
+
+    const selected = candidates[0];
+    if (!selected) {
+      throw new AssistantPluginError(
+        'PLUGIN_BROWSER_PROVIDER_UNAVAILABLE',
+        `No Browser provider satisfies required capabilities: ${options.requiredCapabilities.join(', ') || 'browser.transaction'}.`,
+        { retryable: true },
+      );
+    }
+    await this.prepare(selected);
+    return { provider: selected.provider, generation: selected.generation };
+  }
+}

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

@@ -0,0 +1,154 @@
+export const MAX_BROWSER_CDP_ENDPOINT_CANDIDATES = 5;
+
+export type BrowserProviderCapability =
+  | 'dom.read'
+  | 'dom.interact'
+  | 'browser.internal_resources'
+  | 'browser.screenshot'
+  | 'browser.trusted_input'
+  | 'browser.foreground'
+  | 'browser.transaction'
+  | 'browser.persistent_handle';
+
+export type BrowserTargetOwnership = 'plugin_owned' | 'user_owned' | 'provider_owned';
+export type BrowserTargetKind = 'page' | 'tab' | 'browser_internal_resource';
+export type BrowserForegroundRequirement = 'none' | 'explicit_required';
+export type BrowserActionReplaySafety = 'read_only' | 'idempotent' | 'non_idempotent';
+
+/** Stable resource identity. URL/title are deliberately excluded because they are mutable observations. */
+export interface BrowserTargetIdentity {
+  providerId: string;
+  resourceKind: BrowserTargetKind;
+  resourceId: string;
+  browserProduct?: string;
+  ownership: BrowserTargetOwnership;
+}
+
+export interface BrowserObservedState {
+  url: string;
+  title?: string;
+  observedAt: string;
+  providerRevision?: string;
+}
+
+export interface BrowserProviderCapabilities {
+  providerId: string;
+  capabilities: readonly BrowserProviderCapability[];
+  foreground: BrowserForegroundRequirement;
+  /** True only when the provider can verify postconditions in the same provider call that performs the action. */
+  verifiesPostconditions: boolean;
+  /** True only when an already-bound provider handle can be reused across bounded consecutive actions. */
+  persistentHandle: boolean;
+}
+
+export type BrowserCondition =
+  | { kind: 'target_identity'; target: BrowserTargetIdentity }
+  | { kind: 'url_equals'; url: string }
+  | { kind: 'url_matches'; pattern: string }
+  | { kind: 'selector_exists'; selector: string }
+  | { kind: 'selector_visible'; selector: string }
+  | { kind: 'text_contains'; text: string; selector?: string }
+  | { kind: 'attribute_equals'; selector: string; attribute: string; value: string }
+  | { kind: 'provider_assertion'; assertion: string; expected: string | number | boolean };
+
+export type BrowserTransactionAction =
+  | { kind: 'read'; operation: string; arguments?: Record<string, unknown> }
+  | { kind: 'dom'; operation: string; arguments?: Record<string, unknown> }
+  | { kind: 'internal_resource'; operation: string; arguments?: Record<string, unknown> }
+  | { kind: 'trusted_input'; operation: string; arguments?: Record<string, unknown> };
+
+export interface BrowserTransaction {
+  transactionId: string;
+  target: BrowserTargetIdentity;
+  requiredCapabilities: readonly BrowserProviderCapability[];
+  foreground: BrowserForegroundRequirement;
+  replaySafety: BrowserActionReplaySafety;
+  preconditions?: readonly BrowserCondition[];
+  action: BrowserTransactionAction;
+  /** Writes/interactions require at least one postcondition unless the action itself returns a typed read result. */
+  postconditions?: readonly BrowserCondition[];
+  timeoutMs: number;
+}
+
+export interface BrowserConditionEvidence {
+  condition: BrowserCondition;
+  satisfied: boolean;
+  observed?: unknown;
+  reason?: string;
+}
+
+export interface BrowserTransactionTiming {
+  providerCalls: number;
+  providerDurationMs: number;
+  totalDurationMs: number;
+}
+
+export interface BrowserTransactionResult<T = unknown> {
+  transactionId: string;
+  target: BrowserTargetIdentity;
+  transportSucceeded: boolean;
+  actionPerformed: boolean;
+  /** Authoritative success bit. AX/transport success alone must never set this true. */
+  verified: boolean;
+  result?: T;
+  observedState?: BrowserObservedState;
+  preconditionEvidence: readonly BrowserConditionEvidence[];
+  postconditionEvidence: readonly BrowserConditionEvidence[];
+  timing: BrowserTransactionTiming;
+}
+
+export interface BrowserRuntimeBudget {
+  p95Ms: number;
+  maxProviderCallsWarm: number;
+  maxProviderCallsCold: number;
+  foregroundAllowed: boolean;
+}
+
+/**
+ * Architecture targets, not per-host promises. Live V2 gates report p50/p95 and fail when a
+ * regression materially exceeds these budgets without attributable provider evidence.
+ */
+export const BROWSER_RUNTIME_V2_BUDGETS = {
+  read: { p95Ms: 350, maxProviderCallsWarm: 1, maxProviderCallsCold: 2, foregroundAllowed: false },
+  domInteraction: { p95Ms: 600, maxProviderCallsWarm: 1, maxProviderCallsCold: 2, foregroundAllowed: false },
+  internalResource: { p95Ms: 700, maxProviderCallsWarm: 1, maxProviderCallsCold: 2, foregroundAllowed: false },
+  physicalInput: { p95Ms: 1_500, maxProviderCallsWarm: 1, maxProviderCallsCold: 2, foregroundAllowed: true },
+} as const satisfies Record<string, BrowserRuntimeBudget>;
+
+export function browserTargetKey(target: BrowserTargetIdentity): string {
+  return [target.providerId, target.browserProduct ?? '', target.resourceKind, target.resourceId, target.ownership].join(':');
+}
+
+export function providerSupports(
+  provider: BrowserProviderCapabilities,
+  required: readonly BrowserProviderCapability[],
+): boolean {
+  const available = new Set(provider.capabilities);
+  return required.every((capability) => available.has(capability));
+}
+
+export function browserTransactionVerified(result: BrowserTransactionResult): boolean {
+  return result.transportSucceeded
+    && result.actionPerformed
+    && result.verified
+    && result.preconditionEvidence.every((entry) => entry.satisfied)
+    && result.postconditionEvidence.every((entry) => entry.satisfied);
+}
+
+export function browserTransactionRequiresPostcondition(transaction: BrowserTransaction): boolean {
+  return transaction.replaySafety !== 'read_only';
+}
+
+export function validateBrowserTransaction(transaction: BrowserTransaction): string[] {
+  const errors: string[] = [];
+  if (!transaction.transactionId.trim()) errors.push('transactionId is required');
+  if (!transaction.target.providerId.trim() || !transaction.target.resourceId.trim()) errors.push('stable target identity is incomplete');
+  if (!Number.isFinite(transaction.timeoutMs) || transaction.timeoutMs <= 0) errors.push('timeoutMs must be positive');
+  if (transaction.foreground === 'none' && transaction.requiredCapabilities.includes('browser.foreground')) {
+    errors.push('foreground capability cannot be required by a foreground-free transaction');
+  }
+  if (browserTransactionRequiresPostcondition(transaction) && (transaction.postconditions?.length ?? 0) === 0) {
+    errors.push('interactive transactions require at least one postcondition');
+  }
+  return errors;
+}