@moretea-labs/forge 1.6.0 → 1.7.1

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

@@ -0,0 +1,603 @@
+import type {
+  AssistantPluginActionDescriptor,
+  AssistantPluginCapability,
+  AssistantPluginPermissionScope,
+} from './types';
+
+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';
+
+export function browserPermissions(ready: boolean): AssistantPluginPermissionScope[] {
+  return [
+    {
+      scope: 'browser.read',
+      mode: 'read',
+      description: 'Open pages, extract text, and capture screenshots.',
+      granted: ready,
+      required: true,
+    },
+    {
+      scope: 'browser.interact',
+      mode: 'write',
+      description: 'Click, type, press keys, and wait on allowed browser pages after explicit authorization.',
+      granted: ready,
+      required: true,
+    },
+    {
+      scope: 'browser.profile',
+      mode: 'write',
+      description: 'Persist the dedicated local browser profile, session metadata, and screenshots.',
+      granted: ready,
+      required: true,
+    },
+  ];
+}
+
+export function browserCapabilities(): AssistantPluginCapability[] {
+  return [
+    {
+      capabilityId: 'browser-session',
+      title: 'Browser Sessions',
+      description: 'Create, list, reuse, and close persistent browser sessions.',
+      scopes: ['browser.read', 'browser.profile'],
+      actions: ['create_session', 'list_sessions', 'reconcile_sessions', 'close_session', 'close_page', 'clear_session'],
+    },
+    {
+      capabilityId: 'browser-human-handoff',
+      title: 'Browser Human Handoff',
+      description: 'Present the persistent browser in the foreground, keep it open for manual verification, and resume safely.',
+      scopes: ['browser.read', 'browser.profile'],
+      actions: ['request_human_handoff', 'get_handoff_status', 'resolve_handoff'],
+    },
+    {
+      capabilityId: 'browser-readonly',
+      title: 'Read-only Browser',
+      description: 'Navigate allowed pages, extract DOM/text, capture screenshots, and collect diagnostics.',
+      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',
+        'screenshot', 'extract_links', 'extract_tables', 'extract_forms', 'snapshot_interactive',
+        'get_console_errors', 'get_failed_requests',
+      ],
+    },
+    {
+      capabilityId: 'browser-interaction',
+      title: 'Browser Interaction',
+      description: 'Perform explicit form and pointer interactions on HTTP(S) pages through the persistent Playwright profile.',
+      scopes: ['browser.interact', 'browser.profile'],
+      actions: [
+        'activate_page', 'click', 'click_text', 'double_click', 'hover', 'focus', 'type', 'fill', 'select_option',
+        'check', 'uncheck', 'press', 'keyboard_shortcut', 'trusted_input', 'dispatch_event', 'wait_for_selector', 'attach_local_file', 'await_file_transfer',
+      ],
+    },
+  ];
+}
+
+function sessionTargetSchema(extra: Record<string, unknown> = {}, required: string[] = []): Record<string, unknown> {
+  return {
+    type: 'object',
+    properties: {
+      session_id: { type: 'string' },
+      url: { type: 'string' },
+      wait_until: { type: 'string', enum: ['load', 'domcontentloaded', 'networkidle'] },
+      timeout_ms: { type: 'number' },
+      retries: { type: 'number' },
+      browser_mode: { type: 'string', enum: ['attach_preferred', 'managed_persistent', 'isolated'] },
+      cdp_attach_fallback: { type: 'string', enum: ['managed_persistent', 'fail_closed'] },
+      native_attach_mode: { type: 'string', enum: ['auto', 'disabled'] },
+      native_browser_candidates: { type: 'array', items: { type: 'string', enum: ['vivaldi', 'chrome'] }, maxItems: 2 },
+      ...extra,
+    },
+    ...(required.length > 0 ? { required } : {}),
+    additionalProperties: false,
+  };
+}
+
+const frameScopeProperties = {
+  frame_url: { type: 'string' },
+  frame_name: { type: 'string' },
+};
+
+function interactSchema(extra: Record<string, unknown>, required: string[]): Record<string, unknown> {
+  return sessionTargetSchema({
+    post_action_wait_ms: { type: 'number' },
+    ...extra,
+  }, required);
+}
+
+export function browserActions(): AssistantPluginActionDescriptor[] {
+  const readRemote = [
+    { resource: 'remote' as const, mode: 'read' as const },
+    { resource: 'repo-state' as const, mode: 'write' as const },
+  ];
+  const writeRemote = [
+    { resource: 'remote' as const, mode: 'exclusive' as const },
+    { resource: 'repo-state' as const, mode: 'write' as const },
+  ];
+  const descriptors: AssistantPluginActionDescriptor[] = [
+    {
+      actionId: 'configure',
+      title: 'Configure browser plugin',
+      description: 'Enable or update the local browser plugin configuration.',
+      readOnly: false,
+      risk: 'workspace_write',
+      confirmation: 'authorization',
+      defaultTimeoutMs: 30_000,
+      cancellable: true,
+      idempotent: true,
+      scopes: ['browser.profile'],
+      resourceClaims: [{ resource: 'repo-state', mode: 'write' }],
+      argumentsSchema: {
+        type: 'object',
+        properties: {
+          enabled: { type: 'boolean' },
+          browser_mode: { type: 'string', enum: ['attach_preferred', 'managed_persistent', 'isolated'] },
+          profile_mode: { type: 'string', enum: ['repo_local', 'custom'] },
+          profile_dir: { type: 'string' },
+          profile_directory: { type: 'string' },
+          clear_profile_dir: { type: 'boolean' },
+          clear_profile_directory: { type: 'boolean' },
+          browser_channel: { type: 'string', enum: ['chromium', 'chrome', 'chrome-beta', 'chrome-dev', 'chrome-canary'] },
+          clear_browser_channel: { type: 'boolean' },
+          browser_executable_path: { type: 'string' },
+          clear_browser_executable_path: { type: 'boolean' },
+          cdp_endpoint: { type: 'string' },
+          clear_cdp_endpoint: { type: 'boolean' },
+          cdp_endpoint_candidates: { type: 'array', items: { type: 'string' }, maxItems: MAX_BROWSER_CDP_ENDPOINT_CANDIDATES },
+          clear_cdp_endpoint_candidates: { type: 'boolean' },
+          cdp_discovery_timeout_ms: { type: 'number' },
+          cdp_attach_fallback: { type: 'string', enum: ['managed_persistent', 'fail_closed'] },
+          native_attach_mode: { type: 'string', enum: ['auto', 'disabled'] },
+          native_browser_candidates: { type: 'array', items: { type: 'string', enum: ['vivaldi', 'chrome'] }, maxItems: 2 },
+          default_timeout_ms: { type: 'number' },
+        },
+        additionalProperties: false,
+      },
+    },
+    {
+      actionId: 'create_session',
+      title: 'Create browser session',
+      description: 'Open an HTTP(S) URL or explicitly adopt the matching frontmost native tab, then persist a reusable session id.',
+      readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
+      scopes: ['browser.read', 'browser.profile'], resourceClaims: [{ resource: 'repo-state', mode: 'write' }, ...readRemote],
+      argumentsSchema: sessionTargetSchema({
+        extract_text: { type: 'boolean' },
+        max_chars: { type: 'number' },
+        native_browser_product: { type: 'string', enum: ['chrome', 'vivaldi'] },
+        native_window_id: { type: 'string' },
+        native_tab_id: { type: 'string' },
+        native_active_tab: { type: 'boolean' },
+      }, ['url']),
+    },
+    {
+      actionId: 'list_sessions',
+      title: 'List browser sessions',
+      description: 'List saved browser session metadata without secrets or cookies.',
+      readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 10_000, cancellable: true, idempotent: true,
+      scopes: ['browser.read', 'browser.profile'], resourceClaims: [{ resource: 'repo-state', mode: 'read' }],
+      argumentsSchema: {
+        type: 'object',
+        properties: {
+          limit: { type: 'number', minimum: 1, maximum: MAX_BROWSER_SESSION_LIST_LIMIT, default: DEFAULT_BROWSER_SESSION_LIST_LIMIT },
+          cursor: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+    },
+    {
+      actionId: 'reconcile_sessions',
+      title: 'Reconcile browser sessions',
+      description: 'Prune only saved managed-session metadata whose exact Runtime-bound page is positively proven gone. Never removes profiles, cookies, or unverified native sessions.',
+      readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 15_000, cancellable: true, idempotent: true,
+      scopes: ['browser.read', 'browser.profile'], resourceClaims: [{ resource: 'repo-state', mode: 'write' }],
+      argumentsSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+      actionId: 'close_session',
+      title: 'Close browser session',
+      description: 'Remove one saved session metadata record.',
+      readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 15_000, cancellable: true, idempotent: true,
+      scopes: ['browser.read', 'browser.profile'], resourceClaims: [{ resource: 'repo-state', mode: 'write' }],
+      argumentsSchema: { type: 'object', properties: { session_id: { type: 'string' } }, required: ['session_id'], additionalProperties: false },
+    },
+    {
+      actionId: 'clear_session',
+      title: 'Clear all browser sessions',
+      description: 'Remove all saved session metadata while keeping the profile.',
+      readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 15_000, cancellable: true, idempotent: true,
+      scopes: ['browser.profile'], resourceClaims: [{ resource: 'repo-state', mode: 'write' }],
+      argumentsSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+      actionId: 'request_human_handoff',
+      title: 'Request human browser handoff',
+      description: 'Keep a saved browser session open for CAPTCHA, login, two-factor authentication, or another manual step.',
+      readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: true, idempotent: false,
+      scopes: ['browser.read', 'browser.profile'], resourceClaims: readRemote,
+      argumentsSchema: sessionTargetSchema({
+        reason: { type: 'string', enum: ['captcha', 'login', 'two_factor', 'manual_review', 'sensitive_confirmation'] },
+        instructions: { type: 'string' },
+        handoff_timeout_ms: { type: 'number' },
+      }, ['session_id']),
+    },
+    {
+      actionId: 'get_handoff_status',
+      title: 'Get browser handoff status',
+      description: 'Read durable browser handoff status and reconcile a stale or crashed host.',
+      readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 10_000, cancellable: true, idempotent: true,
+      scopes: ['browser.read', 'browser.profile'], resourceClaims: [{ resource: 'repo-state', mode: 'read' }],
+      argumentsSchema: { type: 'object', properties: { interaction_id: { type: 'string' } }, required: ['interaction_id'], additionalProperties: false },
+    },
+    {
+      actionId: 'resolve_handoff',
+      title: 'Resolve browser handoff',
+      description: 'Resume or cancel a foreground browser handoff.',
+      readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 15_000, cancellable: true, idempotent: true,
+      scopes: ['browser.read', 'browser.profile'], resourceClaims: [{ resource: 'repo-state', mode: 'write' }],
+      argumentsSchema: {
+        type: 'object',
+        properties: {
+          interaction_id: { type: 'string' },
+          resolution: { type: 'string', enum: ['resume', 'cancel'] },
+        },
+        required: ['interaction_id', 'resolution'],
+        additionalProperties: false,
+      },
+    },
+    {
+      actionId: 'open_page',
+      title: 'Open page',
+      description: 'Open an HTTP(S) URL with the persistent profile and save a lightweight session.',
+      readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
+      scopes: ['browser.read'], resourceClaims: readRemote,
+      argumentsSchema: sessionTargetSchema({ extract_text: { type: 'boolean' }, max_chars: { type: 'number' } }, ['url']),
+    },
+    {
+      actionId: 'navigate',
+      title: 'Navigate',
+      description: 'Navigate an existing session or open a new page to an HTTP(S) URL.',
+      readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
+      scopes: ['browser.read', 'browser.interact', 'browser.profile'], resourceClaims: writeRemote,
+      argumentsSchema: sessionTargetSchema({}, ['url']),
+    },
+    {
+      actionId: 'reload',
+      title: 'Reload page',
+      description: 'Reload the current page for a session.',
+      readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
+      scopes: ['browser.read', 'browser.interact', 'browser.profile'], resourceClaims: writeRemote,
+      argumentsSchema: sessionTargetSchema({}, ['session_id']),
+    },
+    {
+      actionId: 'go_back',
+      title: 'Go back',
+      description: 'Navigate back in history for a session.',
+      readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
+      scopes: ['browser.read', 'browser.interact', 'browser.profile'], resourceClaims: writeRemote,
+      argumentsSchema: sessionTargetSchema({}, ['session_id']),
+    },
+    {
+      actionId: 'wait_for_load_state',
+      title: 'Wait for load state',
+      description: 'Wait for load/domcontentloaded/networkidle on a session page.',
+      readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 60_000, cancellable: true, idempotent: true,
+      scopes: ['browser.read'], resourceClaims: readRemote,
+      argumentsSchema: sessionTargetSchema({ state: { type: 'string', enum: ['load', 'domcontentloaded', 'networkidle'] } }),
+    },
+    {
+      actionId: 'get_text',
+      title: 'Get text',
+      description: 'Extract text from a URL or saved browser session.',
+      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' }, max_chars: { type: 'number' }, ...frameScopeProperties }),
+    },
+    {
+      actionId: 'get_html',
+      title: 'Get HTML',
+      description: 'Extract HTML for the page or a selector (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' }, max_chars: { type: 'number' }, ...frameScopeProperties }),
+    },
+    {
+      actionId: 'query_selector',
+      title: 'Query selector',
+      description: 'Return the first matching element summary with a stable selector hint.',
+      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' }, ...frameScopeProperties }, ['selector']),
+    },
+    {
+      actionId: 'query_all',
+      title: 'Query all selectors',
+      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']),
+    },
+    {
+      actionId: 'get_attribute',
+      title: 'Get attribute',
+      description: 'Read one attribute from a selector.',
+      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' }, attribute: { type: 'string' }, ...frameScopeProperties }, ['selector', 'attribute']),
+    },
+    {
+      actionId: 'list_frames',
+      title: 'List page frames',
+      description: 'List bounded Playwright/CDP frame identities for explicit frame-scoped DOM observation.',
+      readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 60_000, cancellable: true, idempotent: true,
+      scopes: ['browser.read'], resourceClaims: [{ resource: 'remote', mode: 'read' }],
+      argumentsSchema: sessionTargetSchema({ limit: { type: 'number', minimum: 1, maximum: 100 } }),
+    },
+    {
+      actionId: 'verify_state',
+      title: 'Verify browser state',
+      description: 'Observe URL, selector existence/visibility, and bounded text criteria in one read-only call for post-action verification.',
+      readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 60_000, cancellable: true, idempotent: true,
+      scopes: ['browser.read'], resourceClaims: [{ resource: 'remote', mode: 'read' }],
+      argumentsSchema: sessionTargetSchema({
+        expected_url: { type: 'string' },
+        url_contains: { type: 'string' },
+        selector: { type: 'string' },
+        require_visible: { type: 'boolean' },
+        text_contains: { type: 'string', maxLength: 10000 },
+        max_chars: { type: 'number', minimum: 1, maximum: 100000 },
+        ...frameScopeProperties,
+      }, ['session_id']),
+    },
+    {
+      actionId: 'screenshot',
+      title: 'Screenshot',
+      description: 'Capture a page, full-page, or element screenshot under browser artifact storage.',
+      readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
+      scopes: ['browser.read'], resourceClaims: readRemote,
+      argumentsSchema: sessionTargetSchema({ full_page: { type: 'boolean' }, selector: { type: 'string' } }),
+    },
+    {
+      actionId: 'extract_links',
+      title: 'Extract links',
+      description: 'Extract anchors with href/text from the page.',
+      readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 60_000, cancellable: true, idempotent: true,
+      scopes: ['browser.read'], resourceClaims: [{ resource: 'remote', mode: 'read' }],
+      argumentsSchema: sessionTargetSchema({ limit: { type: 'number' } }),
+    },
+    {
+      actionId: 'extract_tables',
+      title: 'Extract tables',
+      description: 'Extract simple HTML tables as row arrays.',
+      readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 60_000, cancellable: true, idempotent: true,
+      scopes: ['browser.read'], resourceClaims: [{ resource: 'remote', mode: 'read' }],
+      argumentsSchema: sessionTargetSchema({ limit: { type: 'number' } }),
+    },
+    {
+      actionId: 'extract_forms',
+      title: 'Extract forms',
+      description: 'Extract form field summaries without values that look like secrets.',
+      readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 60_000, cancellable: true, idempotent: true,
+      scopes: ['browser.read'], resourceClaims: [{ resource: 'remote', mode: 'read' }],
+      argumentsSchema: sessionTargetSchema({ limit: { type: 'number' } }),
+    },
+    {
+      actionId: 'snapshot_interactive',
+      title: 'Snapshot interactive elements',
+      description: 'Snapshot interactive elements with stable selector hints plus CSS-pixel viewport geometry for screenshot-to-input grounding.',
+      readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 60_000, cancellable: true, idempotent: true,
+      scopes: ['browser.read'], resourceClaims: [{ resource: 'remote', mode: 'read' }],
+      argumentsSchema: sessionTargetSchema({ limit: { type: 'number' }, ...frameScopeProperties }),
+    },
+    {
+      actionId: 'get_console_errors',
+      title: 'Get console errors',
+      description: 'Return captured console error messages for a page open cycle.',
+      readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 60_000, cancellable: true, idempotent: true,
+      scopes: ['browser.read'], resourceClaims: [{ resource: 'remote', mode: 'read' }],
+      argumentsSchema: sessionTargetSchema({}),
+    },
+    {
+      actionId: 'get_failed_requests',
+      title: 'Get failed requests',
+      description: 'Return failed network requests captured during a page open cycle.',
+      readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 60_000, cancellable: true, idempotent: true,
+      scopes: ['browser.read'], resourceClaims: [{ resource: 'remote', mode: 'read' }],
+      argumentsSchema: sessionTargetSchema({}),
+    },
+    {
+      actionId: 'activate_page',
+      title: 'Activate browser page',
+      description: 'Bring the exact saved browser page/tab to the foreground without opening or replacing a tab.',
+      readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: true,
+      scopes: ['browser.interact', 'browser.profile'], resourceClaims: writeRemote,
+      argumentsSchema: interactSchema({}, []),
+    },
+    {
+      actionId: 'click',
+      title: 'Click element',
+      description: 'Click a selector on an allowed page after authorization.',
+      readOnly: false, risk: 'remote_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
+      scopes: ['browser.interact', 'browser.profile'], resourceClaims: writeRemote,
+      argumentsSchema: interactSchema({ selector: { type: 'string' } }, ['selector']),
+    },
+    {
+      actionId: 'click_text',
+      title: 'Click exact visible text',
+      description: 'Click the smallest visible standard DOM element whose normalized text exactly matches the requested text. Closed shadow roots are intentionally not traversed.',
+      readOnly: false, risk: 'remote_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
+      scopes: ['browser.interact', 'browser.profile'], resourceClaims: writeRemote,
+      argumentsSchema: interactSchema({ text: { type: 'string', minLength: 1, maxLength: 200 } }, ['text']),
+    },
+    {
+      actionId: 'double_click',
+      title: 'Double-click element',
+      description: 'Double-click a selector after authorization.',
+      readOnly: false, risk: 'remote_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
+      scopes: ['browser.interact', 'browser.profile'], resourceClaims: writeRemote,
+      argumentsSchema: interactSchema({ selector: { type: 'string' } }, ['selector']),
+    },
+    {
+      actionId: 'hover',
+      title: 'Hover element',
+      description: 'Hover a selector after authorization.',
+      readOnly: false, risk: 'remote_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
+      scopes: ['browser.interact', 'browser.profile'], resourceClaims: writeRemote,
+      argumentsSchema: interactSchema({ selector: { type: 'string' } }, ['selector']),
+    },
+    {
+      actionId: 'focus',
+      title: 'Focus element',
+      description: 'Focus a selector after authorization.',
+      readOnly: false, risk: 'remote_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
+      scopes: ['browser.interact', 'browser.profile'], resourceClaims: writeRemote,
+      argumentsSchema: interactSchema({ selector: { type: 'string' } }, ['selector']),
+    },
+    {
+      actionId: 'type',
+      title: 'Type into element',
+      description: 'Type text into a selector (append-style) after authorization.',
+      readOnly: false, risk: 'remote_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
+      scopes: ['browser.interact', 'browser.profile'], resourceClaims: writeRemote,
+      argumentsSchema: interactSchema({ selector: { type: 'string' }, text: { type: 'string' } }, ['selector', 'text']),
+    },
+    {
+      actionId: 'fill',
+      title: 'Fill element',
+      description: 'Replace the value of a selector after authorization.',
+      readOnly: false, risk: 'remote_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
+      scopes: ['browser.interact', 'browser.profile'], resourceClaims: writeRemote,
+      argumentsSchema: interactSchema({ selector: { type: 'string' }, text: { type: 'string' } }, ['selector', 'text']),
+    },
+    {
+      actionId: 'select_option',
+      title: 'Select option',
+      description: 'Select one or more option values on a <select> after authorization.',
+      readOnly: false, risk: 'remote_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
+      scopes: ['browser.interact', 'browser.profile'], resourceClaims: writeRemote,
+      argumentsSchema: interactSchema({ selector: { type: 'string' }, values: { type: 'array', items: { type: 'string' } } }, ['selector', 'values']),
+    },
+    {
+      actionId: 'check',
+      title: 'Check checkbox',
+      description: 'Check a checkbox/radio after authorization.',
+      readOnly: false, risk: 'remote_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
+      scopes: ['browser.interact', 'browser.profile'], resourceClaims: writeRemote,
+      argumentsSchema: interactSchema({ selector: { type: 'string' } }, ['selector']),
+    },
+    {
+      actionId: 'uncheck',
+      title: 'Uncheck checkbox',
+      description: 'Uncheck a checkbox after authorization.',
+      readOnly: false, risk: 'remote_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
+      scopes: ['browser.interact', 'browser.profile'], resourceClaims: writeRemote,
+      argumentsSchema: interactSchema({ selector: { type: 'string' } }, ['selector']),
+    },
+    {
+      actionId: 'press',
+      title: 'Press key',
+      description: 'Press a key on a selector on an allowed page after authorization.',
+      readOnly: false, risk: 'remote_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
+      scopes: ['browser.interact', 'browser.profile'], resourceClaims: writeRemote,
+      argumentsSchema: interactSchema({ selector: { type: 'string' }, key: { type: 'string' } }, ['selector', 'key']),
+    },
+    {
+      actionId: 'keyboard_shortcut',
+      title: 'Keyboard shortcut',
+      description: 'Press a keyboard shortcut (e.g. Meta+A) after authorization.',
+      readOnly: false, risk: 'remote_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
+      scopes: ['browser.interact', 'browser.profile'], resourceClaims: writeRemote,
+      argumentsSchema: interactSchema({ key: { type: 'string' } }, ['key']),
+    },
+    {
+      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.',
+      readOnly: false, risk: 'remote_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
+      scopes: ['browser.interact', 'browser.profile'], resourceClaims: writeRemote,
+      argumentsSchema: interactSchema({
+        kind: { type: 'string', enum: ['click', 'move', 'wheel', 'drag', 'key', 'text'] },
+        x: { type: 'number', minimum: 0, maximum: 100000 },
+        y: { type: 'number', minimum: 0, maximum: 100000 },
+        from_x: { type: 'number', minimum: 0, maximum: 100000 },
+        from_y: { type: 'number', minimum: 0, maximum: 100000 },
+        to_x: { type: 'number', minimum: 0, maximum: 100000 },
+        to_y: { type: 'number', minimum: 0, maximum: 100000 },
+        delta_x: { type: 'number', minimum: -100000, maximum: 100000 },
+        delta_y: { type: 'number', minimum: -100000, maximum: 100000 },
+        button: { type: 'string', enum: ['left', 'middle', 'right'] },
+        click_count: { type: 'number', minimum: 1, maximum: 3 },
+        steps: { type: 'number', minimum: 1, maximum: 100 },
+        key: { type: 'string', minLength: 1, maxLength: 100 },
+        text: { type: 'string', maxLength: 10000 },
+        guard_selector: { type: 'string' },
+        ...frameScopeProperties,
+      }, ['kind']),
+    },
+    {
+      actionId: 'dispatch_event',
+      title: 'Dispatch DOM event',
+      description: 'Dispatch one named bubbling/composed DOM CustomEvent on an explicit selector after authorization. No arbitrary JavaScript payload is accepted.',
+      readOnly: false, risk: 'remote_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
+      scopes: ['browser.interact', 'browser.profile'], resourceClaims: writeRemote,
+      argumentsSchema: interactSchema({ selector: { type: 'string' }, event: { type: 'string', minLength: 1, maxLength: 64 } }, ['selector', 'event']),
+    },
+    {
+      actionId: 'wait_for_selector',
+      title: 'Wait for selector',
+      description: 'Wait for a selector state on an allowed page after authorization.',
+      readOnly: true, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: true,
+      scopes: ['browser.interact', 'browser.profile'], resourceClaims: readRemote,
+      argumentsSchema: sessionTargetSchema({
+        selector: { type: 'string' },
+        state: { type: 'string', enum: ['attached', 'detached', 'visible', 'hidden'] },
+      }, ['selector']),
+    },
+    {
+      actionId: 'attach_local_file',
+      title: 'Attach local file(s)',
+      description: 'Set one or more allowed local files on input[type=file] after authorization. file_path remains backward-compatible; file_paths supports multiple selection. Never auto-opens executables.',
+      readOnly: false, risk: 'remote_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
+      scopes: ['browser.interact', 'browser.profile'], resourceClaims: writeRemote,
+      argumentsSchema: interactSchema({
+        selector: { type: 'string' },
+        file_path: { type: 'string' },
+        file_paths: { type: 'array', minItems: 1, maxItems: 32, items: { type: 'string' } },
+      }, ['selector']),
+    },
+    {
+      actionId: 'await_file_transfer',
+      title: 'Await file transfer',
+      description: 'Capture a browser download into bounded artifact storage after authorization. Never auto-opens downloaded files.',
+      readOnly: false, risk: 'remote_write', confirmation: 'authorization', defaultTimeoutMs: 120_000, cancellable: true, idempotent: false,
+      scopes: ['browser.interact', 'browser.profile'], resourceClaims: writeRemote,
+      argumentsSchema: interactSchema({ selector: { type: 'string' }, suggested_name: { type: 'string' } }, ['selector']),
+    },
+    {
+      actionId: 'close_page',
+      title: 'Close session',
+      description: 'Remove saved session metadata while keeping the persistent profile.',
+      readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 15_000, cancellable: true, idempotent: true,
+      scopes: ['browser.read', 'browser.profile'], resourceClaims: [{ resource: 'repo-state', mode: 'write' }],
+      argumentsSchema: { type: 'object', properties: { session_id: { type: 'string' } }, required: ['session_id'], additionalProperties: false },
+    },
+  ];
+  const foregroundRequired = new Set(['activate_page', 'request_human_handoff']);
+  const foregroundPossible = new Set([
+    'create_session', 'open_page', 'navigate', 'reload', 'go_back', 'resolve_handoff',
+    'click', 'click_text', 'double_click', 'hover', 'focus', 'type', 'fill', 'select_option',
+    'check', 'uncheck', 'press', 'keyboard_shortcut', 'trusted_input', 'dispatch_event',
+    'wait_for_selector', 'attach_local_file', 'await_file_transfer',
+  ]);
+  return descriptors.map((descriptor) => ({
+    ...descriptor,
+    foregroundEffect: foregroundRequired.has(descriptor.actionId)
+      ? 'required'
+      : foregroundPossible.has(descriptor.actionId)
+        ? 'possible'
+        : 'none',
+  }));
+}