@moretea-labs/forge 1.5.1 → 1.7.0

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,152 @@
+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;
+}

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

@@ -0,0 +1,183 @@
+import { AssistantPluginError } from './errors';
+import type { AssistantPluginActionExecutionInput } from './types';
+import {
+  validateBrowserTransaction,
+  type BrowserActionReplaySafety,
+  type BrowserForegroundRequirement,
+  type BrowserProviderCapability,
+  type BrowserTargetIdentity,
+  type BrowserTransaction,
+} from './browser-runtime-contract';
+import {
+  BrowserProviderRegistry,
+  BrowserProviderUnavailableBeforeActionError,
+  type BrowserRuntimeProvider,
+} from './browser-provider-registry';
+
+export const ALL_BROWSER_PROVIDER_CAPABILITIES = [
+  'dom.read',
+  'dom.interact',
+  'browser.internal_resources',
+  'browser.screenshot',
+  'browser.trusted_input',
+  'browser.foreground',
+  'browser.transaction',
+  'browser.persistent_handle',
+] as const satisfies readonly BrowserProviderCapability[];
+
+const READ_ACTIONS = new Set([
+  'list_sessions', 'reconcile_sessions', 'get_handoff_status',
+  'get_text', 'get_html', 'query_selector', 'query_all', 'get_attribute', 'list_frames', 'verify_state',
+  'extract_links', 'extract_tables', 'extract_forms', 'snapshot_interactive', 'get_console_errors', 'get_failed_requests',
+  'wait_for_load_state', 'wait_for_selector', 'await_file_transfer',
+]);
+const SCREENSHOT_ACTIONS = new Set(['screenshot']);
+const TRUSTED_INPUT_ACTIONS = new Set(['trusted_input', 'activate_page']);
+const DOM_INTERACTION_ACTIONS = new Set([
+  'create_session', 'open_page', 'navigate', 'reload', 'go_back',
+  'click', 'click_text', 'double_click', 'hover', 'focus', 'type', 'fill', 'select_option', 'check', 'uncheck',
+  'press', 'keyboard_shortcut', 'dispatch_event', 'attach_local_file', 'close_page',
+]);
+const IDEMPOTENT_ACTIONS = new Set(['configure', 'close_session', 'clear_session', 'request_human_handoff', 'resolve_handoff']);
+
+interface BrowserRuntimeActionPolicy {
+  requiredCapabilities: readonly BrowserProviderCapability[];
+  foreground: BrowserForegroundRequirement;
+  replaySafety: BrowserActionReplaySafety;
+}
+
+const registries = new Map<string, BrowserProviderRegistry<AssistantPluginActionExecutionInput, Record<string, unknown>>>();
+
+function registryFor(runtimeKey: string): BrowserProviderRegistry<AssistantPluginActionExecutionInput, Record<string, unknown>> {
+  let registry = registries.get(runtimeKey);
+  if (!registry) {
+    registry = new BrowserProviderRegistry();
+    registries.set(runtimeKey, registry);
+  }
+  return registry;
+}
+
+export function invalidateBrowserRuntime(runtimeKey: string, reason: string): void {
+  registries.get(runtimeKey)?.invalidateAll(reason);
+}
+
+export function browserRuntimeActionPolicy(actionId: string): BrowserRuntimeActionPolicy {
+  if (SCREENSHOT_ACTIONS.has(actionId)) {
+    return { requiredCapabilities: ['browser.screenshot', 'browser.transaction'], foreground: 'none', replaySafety: 'read_only' };
+  }
+  if (TRUSTED_INPUT_ACTIONS.has(actionId)) {
+    return {
+      requiredCapabilities: ['browser.trusted_input', 'browser.foreground', 'browser.transaction'],
+      foreground: 'explicit_required',
+      replaySafety: 'non_idempotent',
+    };
+  }
+  if (READ_ACTIONS.has(actionId)) {
+    return { requiredCapabilities: ['dom.read', 'browser.transaction'], foreground: 'none', replaySafety: 'read_only' };
+  }
+  if (DOM_INTERACTION_ACTIONS.has(actionId)) {
+    return { requiredCapabilities: ['dom.interact', 'browser.transaction'], foreground: 'none', replaySafety: 'non_idempotent' };
+  }
+  return {
+    requiredCapabilities: ['browser.transaction'],
+    foreground: 'none',
+    replaySafety: IDEMPOTENT_ACTIONS.has(actionId) ? 'idempotent' : 'non_idempotent',
+  };
+}
+
+function stringArgument(args: Record<string, unknown>, key: string): string | undefined {
+  const value = args[key];
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function stableTargetFor(input: AssistantPluginActionExecutionInput, providerId: string): BrowserTargetIdentity {
+  const sessionId = stringArgument(input.args, 'session_id');
+  const nativeProduct = stringArgument(input.args, 'native_browser_product');
+  const nativeWindowId = stringArgument(input.args, 'native_window_id');
+  const nativeTabId = stringArgument(input.args, 'native_tab_id');
+  if (nativeWindowId && nativeTabId) {
+    return {
+      providerId,
+      resourceKind: 'tab',
+      resourceId: `window:${nativeWindowId}/tab:${nativeTabId}`,
+      ...(nativeProduct ? { browserProduct: nativeProduct } : {}),
+      ownership: 'user_owned',
+    };
+  }
+  if (sessionId) {
+    return {
+      providerId,
+      resourceKind: 'page',
+      resourceId: `session:${sessionId}`,
+      ownership: 'provider_owned',
+    };
+  }
+  return {
+    providerId,
+    resourceKind: 'page',
+    resourceId: `request:${input.requestId}:${input.actionId}`,
+    ownership: 'plugin_owned',
+  };
+}
+
+function transactionFor(
+  input: AssistantPluginActionExecutionInput,
+  providerId: string,
+  policy: BrowserRuntimeActionPolicy,
+): BrowserTransaction {
+  return {
+    transactionId: input.requestId,
+    target: stableTargetFor(input, providerId),
+    requiredCapabilities: policy.requiredCapabilities,
+    foreground: policy.foreground,
+    replaySafety: policy.replaySafety,
+    action: {
+      kind: policy.replaySafety === 'read_only' ? 'read' : policy.foreground === 'explicit_required' ? 'trusted_input' : 'dom',
+      operation: input.actionId,
+      arguments: input.args,
+    },
+    ...(policy.replaySafety === 'read_only'
+      ? {}
+      : { postconditions: [{ kind: 'provider_assertion', assertion: 'semantic_action_result', expected: true }] as const }),
+    timeoutMs: typeof input.args.timeout_ms === 'number' && Number.isFinite(input.args.timeout_ms)
+      ? Math.max(1, Math.trunc(input.args.timeout_ms))
+      : 60_000,
+  };
+}
+
+export async function executeBrowserRuntimeAction(options: {
+  runtimeKey: string;
+  input: AssistantPluginActionExecutionInput;
+  providers: readonly BrowserRuntimeProvider<AssistantPluginActionExecutionInput, Record<string, unknown>>[];
+}): Promise<Record<string, unknown>> {
+  const registry = registryFor(options.runtimeKey);
+  for (const provider of options.providers) registry.register(provider);
+
+  const policy = browserRuntimeActionPolicy(options.input.actionId);
+  const excluded = new Set<string>();
+  while (true) {
+    const selection = await registry.select({
+      input: options.input,
+      requiredCapabilities: policy.requiredCapabilities,
+      foreground: policy.foreground,
+      excludedProviderIds: excluded,
+    });
+    const transaction = transactionFor(options.input, selection.provider.providerId, policy);
+    const validationErrors = validateBrowserTransaction(transaction);
+    if (validationErrors.length > 0) {
+      throw new AssistantPluginError('PLUGIN_BROWSER_TRANSACTION_INVALID', validationErrors[0]!, {
+        retryable: false,
+        details: { transactionId: transaction.transactionId, errors: validationErrors },
+      });
+    }
+
+    try {
+      return await selection.provider.execute(options.input);
+    } catch (error) {
+      if (!(error instanceof BrowserProviderUnavailableBeforeActionError)) throw error;
+      excluded.add(selection.provider.providerId);
+      // This is provider reselection, not action replay: the typed error proves the rejected provider
+      // never attempted the action. Unknown outcomes from non-idempotent actions always propagate.
+    }
+  }
+}