@browserbridge/bbx 1.12.0 → 1.12.2

package/packages/native-host/src/daemon.js

@@ -32,6 +32,7 @@ import {
   parseJsonLines,
   RecoveryTelemetryCollector,
   normalizeRecoveryTelemetrySummary,
+  sanitizeIncidentalText,
   sanitizeIncidentalValue,
   setProtocolPackageVersion,
   validateBridgeRequest,
@@ -54,6 +55,7 @@ import {
 import { normalizeDaemonLogger } from './daemon-logger.js';
 import { DomBaselineOwnerRegistry, isValidBaselineId } from './dom-baseline-owners.js';
 import { writeJsonLine } from './framing.js';
+import { WindowActionRouter } from './window-actions.js';
 
 const DAEMON_VERSION = loadDaemonVersion();
 setProtocolPackageVersion(DAEMON_VERSION);
@@ -65,7 +67,7 @@ setProtocolPackageVersion(DAEMON_VERSION);
 /** @typedef {import('./config.js').BridgeTransport} BridgeTransport */
 /** @typedef {import('./daemon-logger.js').DaemonLoggerLike} DaemonLoggerLike */
 /** @typedef {'agent' | 'extension'} SocketRole */
-/** @typedef {import('node:net').Socket & { readonly __role?: SocketRole, __localControl?: boolean, __registrationTimeoutId?: NodeJS.Timeout, __invalidLineCount?: number, __clientId?: string, __extensionId?: string, __browserName?: string, __profileLabel?: string, __browserExtensionId?: string, __accessEnabled?: boolean, __lastActiveAt?: number }} ClientSocket */
+/** @typedef {import('node:net').Socket & { readonly __role?: SocketRole, __localControl?: boolean, __registrationTimeoutId?: NodeJS.Timeout, __invalidLineCount?: number, __clientId?: string, __extensionId?: string, __browserName?: string, __profileLabel?: string, __browserExtensionId?: string, __accessEnabled?: boolean, __windowAccessUpdates?: boolean, __windowActions?: boolean, __enabledWindow?: import('../../protocol/src/window-access.js').EnabledWindowInfo | null, __lastActiveAt?: number }} ClientSocket */
 /** @typedef {{ socket: ClientSocket, timeoutId: NodeJS.Timeout, source?: string, mcpEra?: string, method?: string, protocolVersion?: string, baselineId?: string | null, automaticMcpRetry?: boolean, targets: Set<ClientSocket>, lastErrorResponse?: import('../../protocol/src/types.js').BridgeResponse }} PendingEntry */
 /**
  * @typedef {{
@@ -410,12 +412,20 @@ export function isWindowsNamedPipePath(socketPath) {
  *   entry?: Record<string, unknown>,
  *   request?: BridgeRequest,
  *   status?: SetupStatus,
- *   error?: { message?: string },
+ *   error?: { message?: string } | string,
  *   response?: import('../../protocol/src/types.js').BridgeResponse,
  *   browserName?: string,
  *   profileLabel?: string,
  *   browserExtensionId?: string,
  *   accessEnabled?: boolean,
+ *   enabledWindow?: unknown,
+ *   windowAccessUpdates?: boolean,
+ *   windowActions?: boolean,
+ *   action?: unknown,
+ *   windowId?: unknown,
+ *   enabledAt?: unknown,
+ *   extensionId?: unknown,
+ *   ok?: unknown,
  *   authToken?: string,
  *   at?: number
  *   artifactId?: string,
@@ -466,6 +476,7 @@ export class BridgeDaemon {
     this.serverAddress = null;
     /** @type {Map<string, ClientSocket>} */
     this.extensionSockets = new Map();
+    this.windowActions = new WindowActionRouter(this.extensionSockets);
     /** @type {Map<string, ClientSocket>} */
     this.agentSockets = new Map();
     /** @type {Set<ClientSocket>} */
@@ -788,7 +799,9 @@ export class BridgeDaemon {
           if (typedSocket.destroyed) return;
           const message = /** @type {DaemonMessage} */ (raw);
           const admitted =
-            message?.type === 'agent.request' || message?.type === 'extension.setup_status.request';
+            message?.type === 'agent.request' ||
+            message?.type === 'extension.setup_status.request' ||
+            message?.type === 'extension.window_action.request';
           const active = this.activeHandlers.get(typedSocket) ?? 0;
           if (
             admitted &&
@@ -882,6 +895,7 @@ export class BridgeDaemon {
    * @returns {Promise<void>}
    */
   async stopInternal() {
+    this.windowActions.clear();
     for (const pending of this.pendingRequests.values()) {
       clearTimeout(pending.timeoutId);
     }
@@ -978,6 +992,17 @@ export class BridgeDaemon {
       return this.handleExtensionAccessUpdate(socket, message);
     }
 
+    if (
+      message?.type === 'extension.window_action.request' ||
+      message?.type === 'extension.window_action.result'
+    ) {
+      if (socket.__role !== 'extension') return this.rejectMessageForRole(socket, message);
+      if (message.type === 'extension.window_action.request')
+        return this.windowActions.request(socket, message);
+      this.windowActions.result(socket, message);
+      return;
+    }
+
     if (message?.type === 'extension.activity') {
       if (socket.__role !== 'extension') {
         return this.rejectMessageForRole(socket, message);
@@ -1257,7 +1282,9 @@ export class BridgeDaemon {
       typeof request.meta?.target_browser === 'string' ? request.meta.target_browser : null;
     const targetProfile =
       typeof request.meta?.target_profile === 'string' ? request.meta.target_profile : null;
-    const hasExplicitTarget = Boolean(targetBrowser || targetProfile);
+    const targetExtension =
+      typeof request.meta?.target_extension === 'string' ? request.meta.target_extension : null;
+    const hasExplicitTarget = Boolean(targetBrowser || targetProfile || targetExtension);
 
     const ownerPendingCount = this.pendingRequestsByOwnerSocket.get(socket)?.size ?? 0;
     if (
@@ -1286,13 +1313,42 @@ export class BridgeDaemon {
       request.method === 'dom.baseline.describe' ||
       request.method === 'dom.baseline.release';
     const baselineOwner = usesBaselineOwner ? this.domBaselines.get(baselineId ?? '') : null;
+    const candidates = [...this.extensionSockets.entries()].filter(
+      ([id, extension]) =>
+        (!targetExtension || id === targetExtension) &&
+        (!targetBrowser || extension.__browserName === targetBrowser) &&
+        (!targetProfile || extension.__profileLabel === targetProfile)
+    );
+    if (
+      !usesBaselineOwner &&
+      candidates.length > 1 &&
+      request.method !== 'health.ping' &&
+      request.method !== 'skill.get_runtime_context'
+    ) {
+      await writeJsonLine(socket, {
+        type: 'agent.response',
+        response: createFailure(
+          request.id,
+          ERROR_CODES.TAB_MISMATCH,
+          'Multiple browser profiles match this call. Select a connection with extensionId in MCP or meta.target_extension in raw requests, then list its tabs. A tabId alone does not select a profile. Do not disable other windows.',
+          {
+            reason: 'ambiguous_browser_target',
+            connectedExtensions: this.getConnectedExtensionsSnapshot(),
+          },
+          { method: request.method }
+        ),
+      });
+      this.recordDaemonRequestOutcome(request, false);
+      return;
+    }
     const target = usesBaselineOwner
       ? baselineOwner &&
+        (!targetExtension || this.extensionSockets.get(targetExtension) === baselineOwner) &&
         (!targetBrowser || baselineOwner.__browserName === targetBrowser) &&
         (!targetProfile || baselineOwner.__profileLabel === targetProfile)
         ? baselineOwner
         : null
-      : this.selectExtensionTarget(targetBrowser, targetProfile);
+      : this.selectExtensionTarget(targetBrowser, targetProfile, targetExtension);
 
     if (!target) {
       if (usesBaselineOwner) {
@@ -1314,9 +1370,12 @@ export class BridgeDaemon {
         request.id,
         ERROR_CODES.EXTENSION_DISCONNECTED,
         hasExplicitTarget
-          ? `No connected extension matches target_browser="${targetBrowser ?? '*'}" target_profile="${targetProfile ?? '*'}".`
+          ? `No connected extension matches target_browser="${targetBrowser ?? '*'}" target_profile="${targetProfile ?? '*'}" target_extension="${targetExtension ?? '*'}".`
           : 'The Chrome extension is not connected to the local bridge daemon.',
-        null,
+        {
+          reason: hasExplicitTarget ? 'browser_target_disconnected' : 'extension_disconnected',
+          connectedExtensions: this.getConnectedExtensionsSnapshot(),
+        },
         { method: request.method }
       );
       await writeJsonLine(socket, { type: 'agent.response', response });
@@ -1380,6 +1439,7 @@ export class BridgeDaemon {
       if (target.__extensionId && this.extensionSockets.get(target.__extensionId) === target) {
         this.extensionSockets.delete(target.__extensionId);
         this.invalidateConnectedExtensionsCache();
+        this.broadcastWindowAccess();
       }
       target.destroy(error instanceof Error ? error : undefined);
       await this.finishPendingRequestIfExhausted(request.id, pending);
@@ -1392,11 +1452,13 @@ export class BridgeDaemon {
    *
    * @param {string | null} targetBrowser
    * @param {string | null} targetProfile
+   * @param {string | null} [targetExtension]
    * @returns {ClientSocket | null}
    */
-  selectExtensionTarget(targetBrowser, targetProfile) {
-    const candidates = Array.from(this.extensionSockets.entries()).filter(([, extSocket]) => {
+  selectExtensionTarget(targetBrowser, targetProfile, targetExtension = null) {
+    const candidates = Array.from(this.extensionSockets.entries()).filter(([id, extSocket]) => {
       return (
+        (!targetExtension || id === targetExtension) &&
         (!targetBrowser || extSocket.__browserName === targetBrowser) &&
         (!targetProfile || extSocket.__profileLabel === targetProfile)
       );
@@ -1495,6 +1557,10 @@ export class BridgeDaemon {
    */
   handleExtensionIdentity(socket, message) {
     let changed = false;
+    if (message.windowAccessUpdates === true) {
+      socket.__windowAccessUpdates = true;
+    }
+    if (message.windowActions === true) socket.__windowActions = true;
     const browserName = normalizeRoutingLabel(message.browserName);
     if (browserName) {
       changed = changed || socket.__browserName !== browserName;
@@ -1513,6 +1579,7 @@ export class BridgeDaemon {
     if (changed) {
       this.invalidateConnectedExtensionsCache();
     }
+    this.broadcastWindowAccess();
   }
 
   /**
@@ -1522,6 +1589,24 @@ export class BridgeDaemon {
    */
   handleExtensionAccessUpdate(socket, message) {
     const accessEnabled = Boolean(message.accessEnabled);
+    const value = message.enabledWindow;
+    const window =
+      value && typeof value === 'object' ? /** @type {Record<string, unknown>} */ (value) : null;
+    socket.__enabledWindow =
+      accessEnabled &&
+      window &&
+      typeof window.windowId === 'number' &&
+      Number.isInteger(window.windowId) &&
+      window.windowId > 0 &&
+      typeof window.title === 'string' &&
+      typeof window.enabledAt === 'number' &&
+      Number.isFinite(window.enabledAt)
+        ? {
+            windowId: window.windowId,
+            title: sanitizeIncidentalText(window.title).slice(0, 200),
+            enabledAt: window.enabledAt,
+          }
+        : null;
     if (!accessEnabled && socket.__extensionId) {
       this.artifactStore.deleteByExtension(socket.__extensionId);
       this.domBaselines.clearForSocket(socket);
@@ -1529,9 +1614,32 @@ export class BridgeDaemon {
     if (socket.__accessEnabled !== accessEnabled) {
       socket.__accessEnabled = accessEnabled;
       this.invalidateConnectedExtensionsCache();
-      return;
     }
     socket.__accessEnabled = accessEnabled;
+    this.broadcastWindowAccess();
+  }
+
+  /** Broadcast access metadata only to locally authenticated extension connections.
+   * @returns {void}
+   */
+  broadcastWindowAccess() {
+    /** @type {import('../../protocol/src/window-access.js').BrowserWindowAccess[]} */
+    const enabledWindows = [...this.extensionSockets.entries()]
+      .filter(([, socket]) => socket.__accessEnabled === true && !socket.destroyed)
+      .map(([extensionId, socket]) => ({
+        extensionId,
+        browserName: socket.__browserName ?? null,
+        profileLabel: socket.__profileLabel ?? null,
+        window: socket.__enabledWindow ?? null,
+        ...(socket.__windowActions ? { canControl: true } : {}),
+      }));
+    for (const [extensionId, socket] of this.extensionSockets) {
+      if (socket.destroyed || !socket.__windowAccessUpdates) continue;
+      void writeJsonLine(socket, {
+        type: 'extension.window_access',
+        otherEnabledWindows: enabledWindows.filter((window) => window.extensionId !== extensionId),
+      }).catch(() => socket.destroy());
+    }
   }
 
   /**
@@ -1787,6 +1895,7 @@ export class BridgeDaemon {
    * @returns {void}
    */
   handleSocketClose(socket) {
+    this.windowActions.disconnect(socket);
     this.clientSockets.delete(socket);
     if (socket.__registrationTimeoutId) {
       clearTimeout(socket.__registrationTimeoutId);
@@ -1799,6 +1908,7 @@ export class BridgeDaemon {
       if (this.extensionSockets.get(socket.__extensionId) === socket) {
         this.extensionSockets.delete(socket.__extensionId);
         this.invalidateConnectedExtensionsCache();
+        this.broadcastWindowAccess();
       }
     }
 

package/packages/native-host/src/native-host.js

@@ -34,14 +34,17 @@ import { createNativeMessageReader, createNativeMessageWriter, writeJsonLine } f
  *   type?: string,
  *   browserName?: string,
  *   profileLabel?: string,
- *   browserExtensionId?: string
+ *   browserExtensionId?: string,
+ *   windowAccessUpdates?: boolean,
+ *   windowActions?: boolean
  * }} HostIdentityMessage
  */
 
 /**
  * @typedef {{
  *   type?: string,
- *   accessEnabled: boolean
+ *   accessEnabled: boolean,
+ *   enabledWindow?: unknown
  * }} HostAccessUpdateMessage
  */
 
@@ -187,6 +190,23 @@ export async function runNativeHost({
           });
           return;
         }
+        if (message.type === 'extension.window_access') {
+          await writeNativeMessageQueued({
+            type: 'host.window_access',
+            otherEnabledWindows: message.otherEnabledWindows,
+          });
+          return;
+        }
+        if (
+          message.type === 'extension.window_action.command' ||
+          message.type === 'extension.window_action.response'
+        ) {
+          await writeNativeMessageQueued({
+            ...message,
+            type: message.type.replace(/^extension\./u, 'host.'),
+          });
+          return;
+        }
         if (
           message.type === 'extension.setup_status.response' ||
           message.type === 'extension.setup_status.error'
@@ -244,6 +264,8 @@ export async function runNativeHost({
             browserName: message.browserName,
             profileLabel: message.profileLabel,
             browserExtensionId: message.browserExtensionId,
+            ...(message.windowAccessUpdates === true ? { windowAccessUpdates: true } : {}),
+            ...(message.windowActions === true ? { windowActions: true } : {}),
           });
           return;
         }
@@ -251,6 +273,9 @@ export async function runNativeHost({
           await writeJsonLine(socket, {
             type: 'extension.access_update',
             accessEnabled: message.accessEnabled,
+            ...(message.enabledWindow !== undefined
+              ? { enabledWindow: message.enabledWindow }
+              : {}),
           });
           return;
         }
@@ -261,6 +286,19 @@ export async function runNativeHost({
           });
           return;
         }
+        if (message && typeof message === 'object') {
+          const record = /** @type {Record<string, unknown>} */ (message);
+          if (
+            record.type === 'host.window_action.request' ||
+            record.type === 'host.window_action.result'
+          ) {
+            await writeJsonLine(socket, {
+              ...record,
+              type: record.type.replace(/^host\./u, 'extension.'),
+            });
+            return;
+          }
+        }
         if (isHostArtifactMessage(message)) {
           const record = /** @type {Record<string, unknown>} */ (message);
           await writeJsonLine(socket, {

package/packages/native-host/src/window-actions.js

@@ -0,0 +1,115 @@
+// @ts-check
+
+import { randomUUID } from 'node:crypto';
+import { sanitizeIncidentalText } from '../../protocol/src/index.js';
+import { parseWindowActionRequest } from '../../protocol/src/window-actions.js';
+import { writeJsonLine } from './framing.js';
+
+/** @typedef {import('./daemon.js').ClientSocket} ClientSocket */
+/** @typedef {{ source: ClientSocket, target: ClientSocket, finish: (error: string | null) => void }} PendingWindowAction */
+
+/** Relay only user UI actions between authenticated local extensions. */
+export class WindowActionRouter {
+  /** @param {Map<string, ClientSocket>} extensions */
+  constructor(extensions) {
+    this.extensions = extensions;
+    /** @type {Map<string, PendingWindowAction>} */
+    this.pending = new Map();
+  }
+
+  /**
+   * @param {ClientSocket} source
+   * @param {Record<string, unknown>} message
+   * @returns {Promise<void>}
+   */
+  async request(source, message) {
+    const request = parseWindowActionRequest(message);
+    const target = request ? this.extensions.get(request.extensionId) : null;
+    /** @type {string | null} */
+    let error = null;
+    if (
+      !request ||
+      source.__role !== 'extension' ||
+      !source.__windowActions ||
+      this.extensions.get(source.__extensionId ?? '') !== source
+    ) {
+      error = 'Invalid window action request.';
+    } else if (!target || target.destroyed || target === source) {
+      error = 'The other browser disconnected. Refresh the list and try again.';
+    } else if (!target.__windowActions || !target.__enabledWindow) {
+      error = "Update the other browser's extension and native host to control its window.";
+    } else if (
+      !target.__accessEnabled ||
+      target.__enabledWindow.windowId !== request.windowId ||
+      target.__enabledWindow.enabledAt !== request.enabledAt
+    ) {
+      error = 'Window access changed. Refresh the list and try again.';
+    } else if (
+      this.pending.size >= 64 ||
+      [...this.pending.values()].filter((entry) => entry.source === source).length >= 16
+    ) {
+      error = 'Too many window actions are pending. Try again shortly.';
+    } else {
+      const requestId = randomUUID();
+      error = await new Promise((resolve) => {
+        const timer = setTimeout(
+          () => finish('The other browser did not respond. Try again.'),
+          5_000
+        );
+        /** @param {string | null} failure */
+        const finish = (failure) => {
+          if (!this.pending.delete(requestId)) return;
+          clearTimeout(timer);
+          resolve(failure);
+        };
+        this.pending.set(requestId, { source, target, finish });
+        void writeJsonLine(target, {
+          type: 'extension.window_action.command',
+          ...request,
+          requestId,
+        }).catch(() => finish('The other browser disconnected. Try again.'));
+      });
+    }
+    if (!source.destroyed) {
+      await writeJsonLine(source, {
+        type: 'extension.window_action.response',
+        requestId:
+          request?.requestId ??
+          (typeof message.requestId === 'string' ? message.requestId.slice(0, 80) : 'invalid'),
+        ok: error === null,
+        ...(error ? { error } : {}),
+      });
+    }
+  }
+
+  /**
+   * @param {ClientSocket} source
+   * @param {Record<string, unknown>} message
+   * @returns {void}
+   */
+  result(source, message) {
+    const pending =
+      typeof message.requestId === 'string' ? this.pending.get(message.requestId) : null;
+    if (!pending || pending.target !== source) return;
+    pending.finish(
+      message.ok === true
+        ? null
+        : typeof message.error === 'string'
+          ? sanitizeIncidentalText(message.error).slice(0, 200) || 'Window action failed.'
+          : 'Window action failed.'
+    );
+  }
+
+  /** @param {ClientSocket} socket @returns {void} */
+  disconnect(socket) {
+    for (const pending of this.pending.values()) {
+      if (pending.source === socket || pending.target === socket)
+        pending.finish('The browser disconnected. Try again.');
+    }
+  }
+
+  /** @returns {void} */
+  clear() {
+    for (const pending of this.pending.values()) pending.finish('The daemon stopped. Try again.');
+  }
+}

package/packages/protocol/src/protocol.js

@@ -296,7 +296,7 @@ export function createSuccess(id, result, meta = {}) {
  * @returns {BridgeFailureResponse}
  */
 export function createFailure(id, code, message, details = null, meta = {}) {
-  const recovery = getErrorRecovery(code);
+  const recovery = getRoutingRecovery(code, details) ?? getErrorRecovery(code);
   const effectiveRecovery =
     recovery && meta.method === 'sensitive.read'
       ? {
@@ -322,6 +322,35 @@ export function createFailure(id, code, message, details = null, meta = {}) {
   };
 }
 
+/**
+ * Routing errors need selection guidance, not closed-tab or global enable hints.
+ * @param {import('./types.js').ErrorCode} code
+ * @param {unknown} details
+ * @returns {import('./types.js').BridgeRecovery | null}
+ */
+function getRoutingRecovery(code, details) {
+  const reason =
+    details && typeof details === 'object' && 'reason' in details ? details.reason : null;
+  if (
+    (code === ERROR_CODES.TAB_MISMATCH && reason === 'ambiguous_browser_target') ||
+    (code === ERROR_CODES.EXTENSION_DISCONNECTED && reason === 'browser_target_disconnected')
+  ) {
+    return {
+      retry: false,
+      alternativeMethod: 'health.ping',
+      hint: 'Discover connectedExtensions with health.ping or list enabled profiles with MCP tabs.list. Select extensionId and tabId for the intended page. Do not disable unrelated windows or fall back to another profile.',
+    };
+  }
+  if (code === ERROR_CODES.ACCESS_DENIED && reason === 'no_enabled_browser_profiles') {
+    return {
+      retry: false,
+      alternativeMethod: 'health.ping',
+      hint: "Choose the intended extensionId from connectedExtensions before requesting access. Ask the user to enable only that profile's window.",
+    };
+  }
+  return null;
+}
+
 /**
  * @param {unknown} request
  * @returns {BridgeRequest}
@@ -409,6 +438,7 @@ export function validateBridgeRequest(request) {
     params: normalizeRequestParams(method, params),
     meta: {
       ...meta,
+      ...normalizeBrowserTargetMeta(meta),
       protocol_version:
         typeof meta.protocol_version === 'string' ? meta.protocol_version : getProtocolVersion(),
       token_budget: typeof meta.token_budget === 'number' ? meta.token_budget : null,
@@ -424,6 +454,37 @@ export function validateBridgeRequest(request) {
   };
 }
 
+/**
+ * Never turn a malformed explicit selector into implicit routing.
+ * @param {Record<string, unknown>} meta
+ * @returns {Pick<BridgeMeta, 'target_extension' | 'target_browser' | 'target_profile'>}
+ */
+function normalizeBrowserTargetMeta(meta) {
+  /** @type {Pick<BridgeMeta, 'target_extension' | 'target_browser' | 'target_profile'>} */
+  const target = {};
+  for (const field of /** @type {const} */ ([
+    'target_extension',
+    'target_browser',
+    'target_profile',
+  ])) {
+    const value = meta[field];
+    if (value === undefined) continue;
+    if (
+      typeof value !== 'string' ||
+      !value.trim() ||
+      value.length > 256 ||
+      hasAsciiControlCharacters(value)
+    ) {
+      throw new BridgeError(
+        ERROR_CODES.INVALID_REQUEST,
+        `meta.${field} must be a non-empty string of at most 256 characters without control characters.`
+      );
+    }
+    target[field] = value.trim();
+  }
+  return target;
+}
+
 /** @param {string} value @returns {boolean} */
 function hasAsciiControlCharacters(value) {
   for (let index = 0; index < value.length; index += 1) {

package/packages/protocol/src/types.ts

@@ -144,7 +144,17 @@ export type BridgeMethod =
 
 export type CostClass = 'cheap' | 'moderate' | 'heavy' | 'extreme';
 
+/** Browser connection selectors, independent of the machine destination and tab. */
+export interface BrowserTarget {
+  extensionId?: string;
+  targetBrowser?: string;
+  targetProfile?: string;
+}
+
 export interface BridgeMeta {
+  target_extension?: string;
+  target_browser?: string;
+  target_profile?: string;
   protocol_version?: string;
   token_budget?: number | null;
   transport_bytes?: number;

package/packages/protocol/src/window-access.ts

@@ -0,0 +1,29 @@
+/** Window access metadata shared by the native relay and extension UI. */
+export type EnabledWindowInfo = {
+  windowId: number;
+  title: string;
+  enabledAt: number;
+};
+
+export type BrowserWindowAccess = {
+  extensionId: string;
+  browserName: string | null;
+  profileLabel: string | null;
+  window: EnabledWindowInfo | null;
+  canControl?: boolean;
+};
+
+/** Local extension UI actions. These are not agent RPC methods. */
+export type WindowAction = 'focus' | 'disable';
+
+export type WindowActionCommand = {
+  requestId: string;
+  action: WindowAction;
+  windowId: number;
+  enabledAt: number;
+};
+
+export type WindowActionRequest = WindowActionCommand & { extensionId: string };
+
+export type WindowActionResult = { requestId: string; ok: boolean; error?: string };
+export type WindowActionUiResult = { action: WindowAction; ok: boolean; error?: string };

package/packages/protocol/src/window-actions.js

@@ -0,0 +1,46 @@
+// @ts-check
+
+/**
+ * @param {unknown} value
+ * @returns {import('./window-access.js').WindowActionCommand | null}
+ */
+export function parseWindowActionCommand(value) {
+  if (!value || typeof value !== 'object') return null;
+  const message = /** @type {Record<string, unknown>} */ (value);
+  if (
+    typeof message.requestId !== 'string' ||
+    !message.requestId ||
+    message.requestId.length > 80 ||
+    (message.action !== 'focus' && message.action !== 'disable') ||
+    typeof message.windowId !== 'number' ||
+    !Number.isSafeInteger(message.windowId) ||
+    message.windowId <= 0 ||
+    typeof message.enabledAt !== 'number' ||
+    !Number.isFinite(message.enabledAt) ||
+    message.enabledAt < 0
+  )
+    return null;
+  return {
+    requestId: message.requestId,
+    action: message.action,
+    windowId: message.windowId,
+    enabledAt: message.enabledAt,
+  };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {import('./window-access.js').WindowActionRequest | null}
+ */
+export function parseWindowActionRequest(value) {
+  const command = parseWindowActionCommand(value);
+  if (!command) return null;
+  const message = /** @type {Record<string, unknown>} */ (value);
+  if (
+    typeof message.extensionId !== 'string' ||
+    !message.extensionId ||
+    message.extensionId.length > 80
+  )
+    return null;
+  return { ...command, extensionId: message.extensionId };
+}