@moretea-labs/forge 1.7.2 → 1.8.1

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

@@ -1,154 +1,2 @@
-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;
-}
+/** @deprecated C0 compatibility shim. Browser runtime contracts live in packages/plugin-runtime/browser. */
+export * from '../../../packages/plugin-runtime/browser/runtime-contract';

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

@@ -7,12 +7,13 @@ import {
   type BrowserProviderCapability,
   type BrowserTargetIdentity,
   type BrowserTransaction,
-} from './browser-runtime-contract';
+} from '../../../packages/plugin-runtime/browser/runtime-contract';
 import {
   BrowserProviderRegistry,
+  BrowserProviderSelectionError,
   BrowserProviderUnavailableBeforeActionError,
   type BrowserRuntimeProvider,
-} from './browser-provider-registry';
+} from '../../../packages/plugin-runtime/browser/provider-registry';
 
 export const ALL_BROWSER_PROVIDER_CAPABILITIES = [
   'dom.read',
@@ -25,13 +26,38 @@ export const ALL_BROWSER_PROVIDER_CAPABILITIES = [
   'browser.persistent_handle',
 ] as const satisfies readonly BrowserProviderCapability[];
 
+export const DEFAULT_NATIVE_FOREGROUND_VERIFICATION_WAIT_MS = 750;
+
+/**
+ * Normal Browser semantic actions already await the provider primitive and return
+ * bounded post-action evidence. A caller may request an additional compatibility
+ * settle delay explicitly, but omission never creates a hidden fixed sleep.
+ */
+export function browserExplicitPostActionWaitMs(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? Math.trunc(value) : 0;
+}
+
+/**
+ * Native foreground activation is different from ordinary semantic mutation: it
+ * must observe system foreground authority after an Apple Events/Computer action.
+ * Keep its provider-specific verification budget unless the caller explicitly
+ * supplies a non-negative compatibility value.
+ */
+export function browserNativeForegroundVerificationWaitMs(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0
+    ? Math.trunc(value)
+    : DEFAULT_NATIVE_FOREGROUND_VERIFICATION_WAIT_MS;
+}
+
 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',
+  'get_text', 'get_html', 'query_selector', 'query_all', 'get_attribute', 'list_frames', 'verify_state', 'reconcile_effect',
   '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 INTERNAL_RESOURCE_READ_ACTIONS = new Set(['list_unpacked_extensions']);
+const INTERNAL_RESOURCE_MUTATION_ACTIONS = new Set(['install_unpacked_extension']);
 const TRUSTED_INPUT_ACTIONS = new Set(['trusted_input', 'activate_page']);
 const DOM_INTERACTION_ACTIONS = new Set([
   'create_session', 'open_page', 'navigate', 'reload', 'go_back',
@@ -65,6 +91,12 @@ export function browserRuntimeActionPolicy(actionId: string): BrowserRuntimeActi
   if (SCREENSHOT_ACTIONS.has(actionId)) {
     return { requiredCapabilities: ['browser.screenshot', 'browser.transaction'], foreground: 'none', replaySafety: 'read_only' };
   }
+  if (INTERNAL_RESOURCE_READ_ACTIONS.has(actionId)) {
+    return { requiredCapabilities: ['browser.internal_resources', 'browser.transaction'], foreground: 'none', replaySafety: 'read_only' };
+  }
+  if (INTERNAL_RESOURCE_MUTATION_ACTIONS.has(actionId)) {
+    return { requiredCapabilities: ['browser.internal_resources', 'browser.transaction'], foreground: 'none', replaySafety: 'non_idempotent' };
+  }
   if (TRUSTED_INPUT_ACTIONS.has(actionId)) {
     return {
       requiredCapabilities: ['browser.trusted_input', 'browser.foreground', 'browser.transaction'],
@@ -101,6 +133,9 @@ function stringArgument(args: Record<string, unknown>, key: string): string | un
 }
 
 function stableTargetFor(input: AssistantPluginActionExecutionInput, providerId: string): BrowserTargetIdentity {
+  if (INTERNAL_RESOURCE_READ_ACTIONS.has(input.actionId) || INTERNAL_RESOURCE_MUTATION_ACTIONS.has(input.actionId)) {
+    return { providerId, resourceKind: 'browser_internal_resource', resourceId: 'unpacked-extensions', ownership: 'provider_owned' };
+  }
   const sessionId = stringArgument(input.args, 'session_id');
   const nativeProduct = stringArgument(input.args, 'native_browser_product');
   const nativeWindowId = stringArgument(input.args, 'native_window_id');
@@ -142,7 +177,9 @@ function transactionFor(
     foreground: policy.foreground,
     replaySafety: policy.replaySafety,
     action: {
-      kind: policy.replaySafety === 'read_only' ? 'read' : policy.foreground === 'explicit_required' ? 'trusted_input' : 'dom',
+      kind: INTERNAL_RESOURCE_READ_ACTIONS.has(input.actionId) || INTERNAL_RESOURCE_MUTATION_ACTIONS.has(input.actionId)
+        ? 'internal_resource'
+        : policy.replaySafety === 'read_only' ? 'read' : policy.foreground === 'explicit_required' ? 'trusted_input' : 'dom',
       operation: input.actionId,
       arguments: input.args,
     },
@@ -166,12 +203,20 @@ export async function executeBrowserRuntimeAction(options: {
   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,
-    });
+    let selection;
+    try {
+      selection = await registry.select({
+        input: options.input,
+        requiredCapabilities: policy.requiredCapabilities,
+        foreground: policy.foreground,
+        excludedProviderIds: excluded,
+      });
+    } catch (error) {
+      if (error instanceof BrowserProviderSelectionError) {
+        throw new AssistantPluginError(error.code, error.message, { retryable: error.retryable });
+      }
+      throw error;
+    }
     const transaction = transactionFor(options.input, selection.provider.providerId, policy);
     const validationErrors = validateBrowserTransaction(transaction);
     if (validationErrors.length > 0) {