@moretea-labs/forge 1.7.2 → 1.8.0

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

@@ -9,7 +9,7 @@ import {
   type BrowserAutomationTrustedInput,
 } from './browser-automation-service';
 import { AssistantPluginError } from './errors';
-import type { BrowserNativeAttachAttempt, BrowserNativeProduct } from './browser-session-types';
+import type { BrowserNativeAttachAttempt, BrowserNativeProduct } from '../../../packages/protocols/browser/index';
 
 const RECORD_SEPARATOR = String.fromCharCode(30);
 const DEFAULT_NATIVE_TIMEOUT_MS = 5_000;
@@ -267,7 +267,7 @@ async function sendBrowserTrustedInput(
       || /\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.',
+        'The configured Computer input provider does not support native browser trusted input. Keep the exact tab explicitly foregrounded and use a separately grounded Computer interaction, or upgrade the configured provider.',
         { retryable: false, details: { browserProduct: request.product, requiredProviderAction: 'trusted_input' } },
       );
     }
@@ -333,6 +333,15 @@ export function getMacOsBrowserAttachObservation(): MacOsBrowserAttachObservatio
     : undefined;
 }
 
+function recordSuccessfulMacOsBrowserAttachment(attachment: MacOsBrowserAttachment): void {
+  lastAttachObservation = {
+    checkedAt: new Date().toISOString(),
+    ready: true,
+    selectedProduct: attachment.metadata.product,
+    attempts: attachment.attempts.map((attempt) => ({ ...attempt })),
+  };
+}
+
 const BROWSERS: Record<MacOsBrowserProduct, MacOsBrowserDefinition> = {
   chrome: {
     product: 'chrome',
@@ -513,12 +522,17 @@ function createOwnedTabScript(browser: MacOsBrowserDefinition): string {
   return `on run argv
 set targetUrl to item 1 of argv
 ${browserTellScript(browser, `
-if (count of windows) is 0 then error "FORGE_NO_BROWSER_WINDOW"
-set targetWindow to front window
-set originalActiveIndex to active tab index of targetWindow
-set targetTab to make new tab at end of tabs of targetWindow with properties {URL:targetUrl}
+if (count of windows) is 0 then
+  set targetWindow to make new window
+  set targetTab to active tab of targetWindow
+  set URL of targetTab to targetUrl
+else
+  set targetWindow to front window
+  set originalActiveIndex to active tab index of targetWindow
+  set targetTab to make new tab at end of tabs of targetWindow with properties {URL:targetUrl}
+  set active tab index of targetWindow to originalActiveIndex
+end if
 set targetTabId to id of targetTab
-set active tab index of targetWindow to originalActiveIndex
 set separator to ASCII character 30
 return ((id of targetWindow) as text) & separator & (targetTabId as text)
 `)}
@@ -674,18 +688,14 @@ export async function discoverMacOsBrowserAttachment(
   }
   const selectedAttempt = attempts.find((entry) => entry.product === selected.metadata.product);
   if (selectedAttempt) selectedAttempt.status = 'selected';
-  lastAttachObservation = {
-    checkedAt: new Date().toISOString(),
-    ready: true,
-    selectedProduct: selected.metadata.product,
-    attempts: attempts.map((attempt) => ({ ...attempt })),
+  const attachment: MacOsBrowserAttachment = {
+    metadata: selected.metadata,
+    attempts,
   };
+  recordSuccessfulMacOsBrowserAttachment(attachment);
   return {
     attempts,
-    attachment: {
-      metadata: selected.metadata,
-      attempts,
-    },
+    attachment,
   };
 }
 
@@ -1230,10 +1240,13 @@ export class MacOsAppleEventsPage {
 
   private async setChecked(selector: string, checked: boolean): Promise<void> {
     await this.evaluate(selectorSource(selector, `
-      if (!('checked' in element)) throw new Error('Element is not checkable.');
-      element.checked = ${checked};
-      element.dispatchEvent(new Event('input', { bubbles: true }));
-      element.dispatchEvent(new Event('change', { bubbles: true }));
+      if (!('checked' in element) || typeof element.click !== 'function') {
+        throw new Error('Element is not checkable.');
+      }
+      if (element.checked !== ${checked}) element.click();
+      if (element.checked !== ${checked}) {
+        throw new Error('Requested checked state did not persist.');
+      }
       return true;
     `));
   }
@@ -1341,7 +1354,7 @@ async function resolveCurrentMacOsBrowserTabRef(
 ): 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.
+  // production always resolves through the configured Computer provider inventory.
   const inventory = runtimeHooks.tabInventory
     ? await runtimeHooks.tabInventory(product, timeoutMs)
     : runtimeHooks.runAppleScript
@@ -1464,6 +1477,40 @@ export async function createMacOsBrowserOwnedPage(
   return page;
 }
 
+export async function createMacOsBrowserOwnedPageForProduct(
+  product: MacOsBrowserProduct,
+  url: string,
+  attempts: MacOsBrowserAttachAttempt[],
+  timeoutMs = DEFAULT_NATIVE_TIMEOUT_MS,
+): Promise<{ page: MacOsAppleEventsPage; attachment: MacOsBrowserAttachment }> {
+  const browser = browserDefinition(product);
+  const creationEvidence = await runCreateTabAutomation(
+    { action: 'create_tab', product, url },
+    createOwnedTabScript(browser),
+    [url],
+    timeoutMs,
+  );
+  const ref = creationEvidence.ref;
+  const attachment: MacOsBrowserAttachment = {
+    attempts: attempts.map((attempt) => ({ ...attempt })),
+    metadata: {
+      product,
+      appName: browser.appName,
+      bundleId: browser.bundleId,
+      frontmost: false,
+      url,
+      title: '',
+      bounds: { x: 0, y: 0, width: 0, height: 0 },
+      windowId: ref.windowId,
+      tabId: ref.tabId,
+      active: false,
+    },
+  };
+  const page = new MacOsAppleEventsPage(attachment, timeoutMs, ref, creationEvidence);
+  rememberMacOsBrowserPageHandle(product, ref, page);
+  return { page, attachment };
+}
+
 export async function reattachMacOsBrowserOwnedPage(
   product: MacOsBrowserProduct,
   ref: MacOsBrowserTabRef,
@@ -1488,6 +1535,7 @@ export async function reattachMacOsBrowserOwnedPage(
     : ref;
   const page = new MacOsAppleEventsPage(attachment, timeoutMs, resolvedRef);
   rememberMacOsBrowserPageHandle(product, resolvedRef, page);
+  recordSuccessfulMacOsBrowserAttachment(attachment);
   return { page, attachment };
 }
 

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

@@ -7,8 +7,8 @@ import type {
 import {
   DEFAULT_BROWSER_SESSION_LIST_LIMIT,
   MAX_BROWSER_SESSION_LIST_LIMIT,
-} from './browser-session-authority';
-import { MAX_BROWSER_CDP_ENDPOINT_CANDIDATES } from './browser-runtime-contract';
+} from '../../../packages/plugin-runtime/browser/session-authority';
+import { MAX_BROWSER_CDP_ENDPOINT_CANDIDATES } from '../../../packages/plugin-runtime/browser/runtime-contract';
 
 export function browserPermissions(ready: boolean): AssistantPluginPermissionScope[] {
   return [
@@ -59,7 +59,7 @@ export function browserCapabilities(): AssistantPluginCapability[] {
       scopes: ['browser.read', 'browser.profile'],
       actions: [
         'open_page', 'navigate', 'reload', 'go_back', 'wait_for_load_state',
-        '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',
         'screenshot', 'extract_links', 'extract_tables', 'extract_forms', 'snapshot_interactive',
         'get_console_errors', 'get_failed_requests',
       ],
@@ -104,7 +104,7 @@ const frameScopeProperties = {
 
 function interactSchema(extra: Record<string, unknown>, required: string[]): Record<string, unknown> {
   return sessionTargetSchema({
-    post_action_wait_ms: { type: 'number' },
+    post_action_wait_ms: { type: 'number', minimum: 0, description: 'Optional explicit compatibility settle delay after a semantic action. Omit for normal provider completion; native foreground activation retains its provider-specific verification budget.' },
     ...extra,
   }, required);
 }
@@ -318,7 +318,7 @@ export function browserActions(): AssistantPluginActionDescriptor[] {
       description: 'Return matching element summaries (bounded).',
       readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 60_000, cancellable: true, idempotent: true,
       scopes: ['browser.read'], resourceClaims: [{ resource: 'remote', mode: 'read' }],
-      argumentsSchema: sessionTargetSchema({ selector: { type: 'string' }, limit: { type: 'number' }, ...frameScopeProperties }, ['selector']),
+      argumentsSchema: sessionTargetSchema({ selector: { type: 'string' }, limit: { type: 'number' }, from_end: { type: 'boolean' }, ...frameScopeProperties }, ['selector']),
     },
     {
       actionId: 'get_attribute',
@@ -345,13 +345,37 @@ export function browserActions(): AssistantPluginActionDescriptor[] {
       argumentsSchema: sessionTargetSchema({
         expected_url: { type: 'string' },
         url_contains: { type: 'string' },
+        url_contains_any: { type: 'array', minItems: 1, maxItems: 16, items: { type: 'string', maxLength: 2000 } },
+        url_contains_none: { type: 'array', minItems: 1, maxItems: 16, items: { type: 'string', maxLength: 2000 } },
         selector: { type: 'string' },
         require_visible: { type: 'boolean' },
         text_contains: { type: 'string', maxLength: 10000 },
+        text_contains_any: { type: 'array', minItems: 1, maxItems: 16, items: { type: 'string', maxLength: 10000 } },
+        text_contains_none: { type: 'array', minItems: 1, maxItems: 16, items: { type: 'string', maxLength: 10000 } },
         max_chars: { type: 'number', minimum: 1, maximum: 100000 },
         ...frameScopeProperties,
       }, ['session_id']),
     },
+    {
+      actionId: 'reconcile_effect',
+      title: 'Reconcile browser effect',
+      description: 'Read the already-bound browser session and classify one exact prior effect request as applied, not_applied, or unknown from declared observation criteria. Never navigates or replays the effect.',
+      readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 60_000, cancellable: true, idempotent: true,
+      scopes: ['browser.read'], resourceClaims: [{ resource: 'remote', mode: 'read' }],
+      argumentsSchema: sessionTargetSchema({
+        effect_request_id: { type: 'string' },
+        applied_url_contains_any: { type: 'array', minItems: 1, maxItems: 16, items: { type: 'string', maxLength: 2000 } },
+        applied_url_contains_none: { type: 'array', minItems: 1, maxItems: 16, items: { type: 'string', maxLength: 2000 } },
+        applied_text_contains_any: { type: 'array', minItems: 1, maxItems: 16, items: { type: 'string', maxLength: 10000 } },
+        applied_text_contains_none: { type: 'array', minItems: 1, maxItems: 16, items: { type: 'string', maxLength: 10000 } },
+        applied_selector: { type: 'string' },
+        not_applied_url_contains_any: { type: 'array', minItems: 1, maxItems: 16, items: { type: 'string', maxLength: 2000 } },
+        not_applied_text_contains_any: { type: 'array', minItems: 1, maxItems: 16, items: { type: 'string', maxLength: 10000 } },
+        not_applied_selector: { type: 'string' },
+        max_chars: { type: 'number', minimum: 1, maximum: 100000 },
+        ...frameScopeProperties,
+      }, ['session_id', 'effect_request_id']),
+    },
     {
       actionId: 'screenshot',
       title: 'Screenshot',
@@ -515,7 +539,7 @@ export function browserActions(): AssistantPluginActionDescriptor[] {
     {
       actionId: 'trusted_input',
       title: 'Trusted browser input',
-      description: 'Send bounded mouse, wheel, drag, key, or text input after authorization. Playwright/CDP uses page input primitives; native macOS sessions require the exact saved tab to already be foreground/active and use the stable Desktop Operator input broker without activating another tab.',
+      description: 'Send bounded mouse, wheel, drag, key, or text input after authorization. Playwright/CDP uses page input primitives; native sessions require the exact saved tab to already be foreground/active and use the configured Computer input provider without activating another tab.',
       readOnly: false, risk: 'remote_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
       scopes: ['browser.interact', 'browser.profile'], resourceClaims: writeRemote,
       argumentsSchema: interactSchema({

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

@@ -7,7 +7,7 @@ import {
   type MacOsBrowserProduct,
 } from './browser-macos-bridge';
 import { listSavedBrowserSessions, removeBrowserSession } from './browser-session-store';
-import type { BrowserSessionInventoryItem, BrowserSessionState } from './browser-session-types';
+import type { BrowserSessionInventoryItem, BrowserSessionState } from '../../../packages/protocols/browser/index';
 
 export interface NativeOwnedSessionInspection {
   items: Map<string, BrowserSessionInventoryItem>;

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

@@ -1,109 +1,2 @@
-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 };
-  }
-}
+/** @deprecated C0 compatibility shim. Browser provider selection lives in packages/plugin-runtime/browser. */
+export * from '../../../packages/plugin-runtime/browser/provider-registry';

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

@@ -0,0 +1,16 @@
+import {
+  buildBrowserPluginManifest,
+  executeBrowserPluginAction,
+  resolveBrowserPluginAuthorizationContext,
+} from './browser-adapter';
+import type { AssistantPluginAdapter } from './types';
+
+/** Thin first-party registration. Browser execution remains an adapter implementation detail. */
+export const browserPluginAdapter: AssistantPluginAdapter = {
+  pluginId: 'browser',
+  scope: 'controller_with_repository_overlay',
+  exposure: 'internal',
+  buildManifest: buildBrowserPluginManifest,
+  executeAction: executeBrowserPluginAction,
+  resolveAuthorizationContext: resolveBrowserPluginAuthorizationContext,
+};

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,9 +26,32 @@ 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',
 ]);
@@ -166,12 +190,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) {