@mearl/native-host 2.7.1 → 2.7.2

package/dist/agentbay-browser.d.ts

@@ -42,6 +42,23 @@ export interface AgentBaySessionLike {
             errorMessage?: string;
         }>;
     };
+    fileSystem?: {
+        getFileTransferContextPath(): Promise<string | null>;
+        createDirectory(path: string): Promise<{
+            success?: boolean;
+            error?: string;
+            errorMessage?: string;
+        }>;
+        uploadFile(localPath: string, remotePath: string, options?: {
+            wait?: boolean;
+            waitTimeout?: number;
+        }): Promise<{
+            success?: boolean;
+            error?: string;
+            errorMessage?: string;
+            error_message?: string;
+        }>;
+    };
     delete(syncContext?: boolean): Promise<{
         success: boolean;
         errorMessage?: string;
@@ -130,6 +147,7 @@ export declare function normalizeDesktopUserAgent(value: unknown): string;
 export declare function normalizeAgentBayAccessUrl(value: unknown): string | undefined;
 export declare function hasAgentBayBrowser(selector: string): boolean;
 export declare function listAgentBayBrowsers(): AgentBayBrowserSummary[];
+export declare function getAgentBaySession(sessionId: string, dependencies?: Pick<AgentBayBrowserManagerDeps, 'createAgentBayClient' | 'resolveApiKey'>): Promise<AgentBaySessionLike>;
 export declare function getAgentBayAccessUrl(sessionId: string, dependencies?: Pick<AgentBayBrowserManagerDeps, 'createAgentBayClient' | 'resolveApiKey'>): Promise<string>;
 export declare function resolveAgentBayEndpoint(sessionId: string): Promise<string>;
 export declare function keepAgentBaySessionAlive(sessionId: string): Promise<void>;

package/dist/agentbay-file-upload.d.ts

@@ -0,0 +1,12 @@
+import { type AgentBaySessionLike } from './agentbay-browser.js';
+interface AgentBayPageUploadDependencies {
+    getSession?: (sessionId: string) => Promise<AgentBaySessionLike>;
+    createTransferId?: () => string;
+}
+/**
+ * Copies Native Host-local files into the active AgentBay session before CDP selects them.
+ * Each file gets an isolated directory so the browser-visible filename stays unchanged.
+ * Staged files remain session-scoped because Chromium may read them after the CDP call returns.
+ */
+export declare function stageAgentBayPageUploads(sessionId: string, action: string, data: any, dependencies?: AgentBayPageUploadDependencies): Promise<any>;
+export {};

package/dist/cdp-backend/buffers.d.ts

@@ -45,6 +45,7 @@ export interface CdpBuffers {
     capture: CaptureSequenceState & {
         droppedRequestsThroughSequence: number;
         droppedLogsThroughSequence: number;
+        droppedEventsThroughSequence: number;
     };
 }
 export declare function createBuffers(tabId?: number): CdpBuffers;

package/dist/cdp-backend/composite-handlers.d.ts

@@ -10,9 +10,8 @@ import type { CdpSession } from './cdp-session.js';
 import { type ControlSource, type PageActAction, type RunActionsParams } from '@mearl/browser-core';
 export declare function cdpRunActions(session: CdpSession, data: RunActionsParams, controlSource?: ControlSource): Promise<any>;
 /**
- * Runs a page interaction action with built-in observation and diagnostic
- * deltas. `observe: false` disables DOM/navigation observation;
- * `diagnostics: false` also disables the atomic console/network result.
+ * Runs a page interaction action with built-in observation. Diagnostics are
+ * collected only when the caller requests them.
  * `run_actions` stays lightweight and never enters this wrapper.
  */
 export declare function cdpObservedPageAction(session: CdpSession, action: PageActAction, data: any, controlSource?: ControlSource): Promise<any>;

package/dist/index.js

@@ -1002,6 +1002,83 @@ function parseTrackingRequest(url2, postData, options = {}) {
   return armsEvent ? [armsEvent] : [];
 }
 
+// ../browser-core/dist/capture.js
+var CURSOR_PREFIX = "mearl-capture-v1";
+function createCaptureGeneration() {
+  return crypto.randomUUID();
+}
+function encodeCaptureCursor(cursor) {
+  return `${CURSOR_PREFIX}:${cursor.tabId}:${cursor.generation}:${cursor.scope}:${cursor.sequence}`;
+}
+function decodeCaptureCursor(value) {
+  const match = value.match(/^mearl-capture-v1:(\d+):([^:]+):(all|logs|requests|events):(\d+)$/);
+  if (!match)
+    throw new Error("Invalid capture cursor");
+  const tabId = Number(match[1]);
+  const sequence = Number(match[4]);
+  if (!Number.isSafeInteger(tabId) || !Number.isSafeInteger(sequence)) {
+    throw new Error("Invalid capture cursor");
+  }
+  return {
+    tabId,
+    generation: match[2],
+    scope: match[3],
+    sequence
+  };
+}
+function captureCheckpoint(state) {
+  return encodeCaptureCursor({
+    tabId: state.tabId,
+    generation: state.generation,
+    sequence: state.currentSequence,
+    scope: "all"
+  });
+}
+function nextCaptureSequence(state) {
+  state.currentSequence += 1;
+  return state.currentSequence;
+}
+function resolveAfterSequence(after, state, scope) {
+  if (!after)
+    return 0;
+  const cursor = decodeCaptureCursor(after);
+  if (cursor.tabId !== state.tabId) {
+    throw new Error(`Capture cursor belongs to tab ${cursor.tabId}, not tab ${state.tabId}`);
+  }
+  if (cursor.generation !== state.generation) {
+    throw new Error("Capture cursor expired because the tab collector was restarted");
+  }
+  if (cursor.scope !== "all" && cursor.scope !== scope) {
+    throw new Error(`Capture cursor is scoped to ${cursor.scope}, not ${scope}`);
+  }
+  if (cursor.sequence > state.currentSequence) {
+    throw new Error("Capture cursor is ahead of the current collector state");
+  }
+  return cursor.sequence;
+}
+function queryCapturedEntries(buffer, state, options, matches, droppedThroughSequence = 0, scope = "all") {
+  const { after, since, now = Date.now() } = options;
+  const limit = Math.max(1, Math.floor(options.limit ?? 100));
+  const afterSequence = resolveAfterSequence(after, state, scope);
+  const sinceTimestampMs = since === void 0 ? void 0 : now - since * 1e3;
+  const matched = buffer.filter((entry) => entry.captureSequence > afterSequence && (sinceTimestampMs === void 0 || entry.timestampMs >= sinceTimestampMs) && matches(entry));
+  const hasMore = matched.length > limit;
+  const entries = after ? matched.slice(0, limit) : matched.slice(-limit);
+  const nextSequence = after && hasMore && entries.length > 0 ? entries[entries.length - 1].captureSequence : state.currentSequence;
+  return {
+    entries,
+    totalMatched: matched.length,
+    nextCursor: encodeCaptureCursor({
+      tabId: state.tabId,
+      generation: state.generation,
+      sequence: nextSequence,
+      scope
+    }),
+    hasMore,
+    gap: after !== void 0 && afterSequence < droppedThroughSequence
+  };
+}
+
 // ../browser-core/dist/eventFilters.js
 var TRACKING_CAPTURE_ARMED_HINT = "Event capture is active, but this tab has no captured history yet. Reload the current tab or repeat the triggering action, then call get_events again.";
 function compileTextPattern(value) {
@@ -1030,15 +1107,31 @@ function compactEventUrl(value) {
   }
 }
 function formatTrackingEvent(event, includeRaw = false) {
+  const { captureSequence: _discardedCaptureSequence, ...publicEvent } = event;
   if (includeRaw)
-    return event;
-  const { _raw: _discardedRaw, _context, url: url2, ...summary } = event;
+    return publicEvent;
+  const { _raw: _discardedRaw, _context, url: url2, ...summary } = publicEvent;
   const compactUrl = compactEventUrl(url2 ?? _context.requestUrl);
   return {
     ...summary,
     ...compactUrl ? { url: compactUrl } : {}
   };
 }
+function matchesTrackingEvent(event, options) {
+  const { source = "all", event_type, filter } = options;
+  if (source !== "all" && event.source !== source)
+    return false;
+  if (event_type && !matchesTextPattern(event.event_type, compileTextPattern(event_type))) {
+    return false;
+  }
+  if (filter) {
+    const pattern = compileTextPattern(filter);
+    if (!matchesTextPattern(event.name, pattern) && !matchesTextPattern(event.url, pattern)) {
+      return false;
+    }
+  }
+  return true;
+}
 function queryTrackingEvents(buffer, options = {}) {
   const { source = "all", event_type, filter, since, limit = 20, now = Date.now() } = options;
   let events = [...buffer].reverse();
@@ -1063,6 +1156,84 @@ function queryTrackingEvents(buffer, options = {}) {
     totalInBuffer: buffer.length
   };
 }
+function appendCapturedTrackingBatch(buffer, events, maxSize) {
+  if (events.length === 0)
+    return [];
+  const captureSequence = events[0].captureSequence;
+  const insertionIndex = Number.isSafeInteger(captureSequence) ? buffer.findIndex((event) => Number.isSafeInteger(event.captureSequence) && event.captureSequence > captureSequence) : -1;
+  buffer.splice(insertionIndex < 0 ? buffer.length : insertionIndex, 0, ...events);
+  if (buffer.length <= maxSize)
+    return [];
+  let removeCount = buffer.length - maxSize;
+  const boundarySequence = buffer[removeCount - 1]?.captureSequence;
+  while (boundarySequence !== void 0 && buffer[removeCount]?.captureSequence === boundarySequence) {
+    removeCount += 1;
+  }
+  return buffer.splice(0, removeCount);
+}
+function queryCapturedTrackingEvents(buffer, state, options = {}, droppedThroughSequence = 0) {
+  const limit = Math.max(1, Math.floor(options.limit ?? 20));
+  if (!options.after) {
+    const snapshot = queryTrackingEvents(buffer, options);
+    return {
+      ...snapshot,
+      nextCursor: encodeCaptureCursor({
+        tabId: state.tabId,
+        generation: state.generation,
+        sequence: state.currentSequence,
+        scope: "events"
+      }),
+      hasMore: snapshot.totalMatched > limit,
+      gap: false
+    };
+  }
+  const sinceTimestampMs = options.since === void 0 ? void 0 : (options.now ?? Date.now()) - options.since * 1e3;
+  const batchesBySequence = /* @__PURE__ */ new Map();
+  for (const event of buffer) {
+    if (!Number.isSafeInteger(event.captureSequence))
+      continue;
+    if (sinceTimestampMs !== void 0 && event.batchTimestampMs < sinceTimestampMs)
+      continue;
+    if (!matchesTrackingEvent(event, options))
+      continue;
+    const captureSequence = event.captureSequence;
+    const batch = batchesBySequence.get(captureSequence);
+    if (batch)
+      batch.events.push(event);
+    else {
+      batchesBySequence.set(captureSequence, {
+        captureSequence,
+        timestampMs: event.batchTimestampMs,
+        events: [event]
+      });
+    }
+  }
+  const batches = [...batchesBySequence.values()].sort((left, right) => left.captureSequence - right.captureSequence);
+  const captured = queryCapturedEntries(batches, state, { after: options.after, limit: Number.MAX_SAFE_INTEGER }, () => true, droppedThroughSequence, "events");
+  const selected = [];
+  let selectedCount = 0;
+  for (const batch of captured.entries) {
+    if (selected.length > 0 && selectedCount + batch.events.length > limit)
+      break;
+    selected.push(batch);
+    selectedCount += batch.events.length;
+  }
+  const hasMore = selected.length < captured.entries.length;
+  const nextSequence = hasMore ? selected[selected.length - 1].captureSequence : state.currentSequence;
+  return {
+    events: selected.flatMap((batch) => batch.events),
+    totalMatched: captured.entries.reduce((total, batch) => total + batch.events.length, 0),
+    totalInBuffer: buffer.length,
+    nextCursor: encodeCaptureCursor({
+      tabId: state.tabId,
+      generation: state.generation,
+      sequence: nextSequence,
+      scope: "events"
+    }),
+    hasMore,
+    gap: captured.gap
+  };
+}
 
 // ../browser-core/dist/requestSerializer.js
 function parsePath(path15) {
@@ -3578,6 +3749,7 @@ var PAGE_ACT_ACTIONS = [
   "page_eval"
 ];
 var BROWSER_COMMAND_ACTIONS = {
+  tab_checkpoint: true,
   capture_checkpoint: true,
   get_requests: true,
   get_logs: true,
@@ -3622,6 +3794,7 @@ var BROWSER_COMMAND_ACTIONS = {
   run_actions: true
 };
 var EXTENSION_BROWSER_ACTIONS = {
+  tab_checkpoint: true,
   capture_checkpoint: true,
   get_requests: true,
   get_logs: true,
@@ -3674,22 +3847,53 @@ var DEFAULT_PAGE_DIAGNOSTICS = {
   logs: true,
   requests: true
 };
+var PageActionPreconditionError = class extends Error {
+  pageActionFailureStage = "precondition";
+  constructor(message, options) {
+    super(message, options);
+    this.name = "PageActionPreconditionError";
+  }
+};
+function isPageActionPreconditionError(error48) {
+  return typeof error48 === "object" && error48 !== null && error48.pageActionFailureStage === "precondition";
+}
+function asPageActionPreconditionError(error48) {
+  if (isPageActionPreconditionError(error48))
+    return error48;
+  return new PageActionPreconditionError(error48 instanceof Error ? error48.message : String(error48), {
+    cause: error48
+  });
+}
+function checkPageActionPrecondition(check2) {
+  try {
+    return check2();
+  } catch (error48) {
+    throw asPageActionPreconditionError(error48);
+  }
+}
+function describePageActionFailure(error48) {
+  return {
+    error: error48 instanceof Error ? error48.message : String(error48),
+    ...isPageActionPreconditionError(error48) ? { stage: error48.pageActionFailureStage } : {}
+  };
+}
 function isPageActAction(action) {
   return PAGE_ACT_ACTIONS.includes(action);
 }
 function shouldObservePageAction(action, data) {
   if (!isPageActAction(action))
     return false;
-  const diagnosticsEnabled = data?.diagnostics !== void 0 && data.diagnostics !== false;
+  const diagnosticsSetting = data?.diagnostics;
+  const diagnosticsEnabled = diagnosticsSetting === true || diagnosticsSetting !== null && typeof diagnosticsSetting === "object" && !Array.isArray(diagnosticsSetting);
   if (action === "page_eval") {
     return Boolean(diagnosticsEnabled || data?.observe && typeof data.observe === "object" && !Array.isArray(data.observe));
   }
-  return data?.observe !== false || data?.diagnostics !== false;
+  return data?.observe !== false || diagnosticsEnabled;
 }
 function splitObservedActionPayload(action, data) {
   const { observe, diagnostics, ...actionData } = data ?? {};
   const setting = diagnostics;
-  const resolvedDiagnostics = setting === false ? void 0 : setting === true ? DEFAULT_PAGE_DIAGNOSTICS : setting && typeof setting === "object" && !Array.isArray(setting) ? setting : action === "page_eval" ? void 0 : DEFAULT_PAGE_DIAGNOSTICS;
+  const resolvedDiagnostics = setting === false ? void 0 : setting === true ? DEFAULT_PAGE_DIAGNOSTICS : setting && typeof setting === "object" && !Array.isArray(setting) ? setting : void 0;
   if (observe === false)
     return { actionData, observe: false, diagnostics: resolvedDiagnostics };
   if (action === "page_eval" && (!observe || typeof observe !== "object")) {
@@ -3752,11 +3956,25 @@ async function runPageAct(input, dependencies) {
     sourceTabId
   }).catch(() => null);
   let actionResult;
-  let actionError;
+  let actionFailure;
   try {
     actionResult = await dependencies.executeAction(typedAction, actionData);
   } catch (error48) {
-    actionError = error48 instanceof Error ? error48.message : String(error48);
+    actionFailure = describePageActionFailure(error48);
+  }
+  if (actionFailure?.stage === "precondition") {
+    await Promise.allSettled([
+      Promise.resolve().then(() => navigationObserver?.dispose()),
+      Promise.resolve().then(() => dependencies.disposeObservation?.())
+    ]);
+    return {
+      action: {
+        name: typedAction,
+        success: false,
+        error: actionFailure.error,
+        stage: actionFailure.stage
+      }
+    };
   }
   let observation;
   try {
@@ -3765,13 +3983,13 @@ async function runPageAct(input, dependencies) {
     observation = unavailableObservation(checkpoint, error48);
   }
   try {
-    if (navigationObserver && actionError === void 0 && (navigationObserver.hasStarted() || shouldWaitForPotentialNavigation(typedAction, observation))) {
+    if (navigationObserver && actionFailure === void 0 && (navigationObserver.hasStarted() || shouldWaitForPotentialNavigation(typedAction, observation))) {
       const didNavigate = navigationObserver.hasStarted() || await navigationObserver.waitForStart(navigationOptions.graceMs);
       if (didNavigate) {
         observation = await navigationObserver.waitForResult(navigationOptions.timeoutMs);
       }
     }
-    if (navigationObserver && actionError === void 0 && observation.mode !== "navigation" && navigationObserver.hasNetworkActivity()) {
+    if (navigationObserver && actionFailure === void 0 && observation.mode !== "navigation" && navigationObserver.hasNetworkActivity()) {
       const network = await navigationObserver.waitForNetworkIdle(navigationOptions.timeoutMs);
       if (navigationObserver.hasStarted()) {
         observation = await navigationObserver.waitForResult(navigationOptions.timeoutMs);
@@ -3806,9 +4024,9 @@ async function runPageAct(input, dependencies) {
   return {
     action: {
       name: typedAction,
-      success: actionError === void 0,
+      success: actionFailure === void 0,
       ...actionResult !== void 0 ? { data: actionResult } : {},
-      ...actionError ? { error: actionError } : {}
+      ...actionFailure ? actionFailure : {}
     },
     observation: compactObservationResponse(observation, checkpoint)
   };
@@ -4566,83 +4784,6 @@ ${SOURCE_BADGES[source]}
   return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
 }
 
-// ../browser-core/dist/capture.js
-var CURSOR_PREFIX = "mearl-capture-v1";
-function createCaptureGeneration() {
-  return crypto.randomUUID();
-}
-function encodeCaptureCursor(cursor) {
-  return `${CURSOR_PREFIX}:${cursor.tabId}:${cursor.generation}:${cursor.scope}:${cursor.sequence}`;
-}
-function decodeCaptureCursor(value) {
-  const match = value.match(/^mearl-capture-v1:(\d+):([^:]+):(all|logs|requests):(\d+)$/);
-  if (!match)
-    throw new Error("Invalid capture cursor");
-  const tabId = Number(match[1]);
-  const sequence = Number(match[4]);
-  if (!Number.isSafeInteger(tabId) || !Number.isSafeInteger(sequence)) {
-    throw new Error("Invalid capture cursor");
-  }
-  return {
-    tabId,
-    generation: match[2],
-    scope: match[3],
-    sequence
-  };
-}
-function captureCheckpoint(state) {
-  return encodeCaptureCursor({
-    tabId: state.tabId,
-    generation: state.generation,
-    sequence: state.currentSequence,
-    scope: "all"
-  });
-}
-function nextCaptureSequence(state) {
-  state.currentSequence += 1;
-  return state.currentSequence;
-}
-function resolveAfterSequence(after, state, scope) {
-  if (!after)
-    return 0;
-  const cursor = decodeCaptureCursor(after);
-  if (cursor.tabId !== state.tabId) {
-    throw new Error(`Capture cursor belongs to tab ${cursor.tabId}, not tab ${state.tabId}`);
-  }
-  if (cursor.generation !== state.generation) {
-    throw new Error("Capture cursor expired because the tab collector was restarted");
-  }
-  if (cursor.scope !== "all" && cursor.scope !== scope) {
-    throw new Error(`Capture cursor is scoped to ${cursor.scope}, not ${scope}`);
-  }
-  if (cursor.sequence > state.currentSequence) {
-    throw new Error("Capture cursor is ahead of the current collector state");
-  }
-  return cursor.sequence;
-}
-function queryCapturedEntries(buffer, state, options, matches, droppedThroughSequence = 0, scope = "all") {
-  const { after, since, now = Date.now() } = options;
-  const limit = Math.max(1, Math.floor(options.limit ?? 100));
-  const afterSequence = resolveAfterSequence(after, state, scope);
-  const sinceTimestampMs = since === void 0 ? void 0 : now - since * 1e3;
-  const matched = buffer.filter((entry) => entry.captureSequence > afterSequence && (sinceTimestampMs === void 0 || entry.timestampMs >= sinceTimestampMs) && matches(entry));
-  const hasMore = matched.length > limit;
-  const entries = after ? matched.slice(0, limit) : matched.slice(-limit);
-  const nextSequence = after && hasMore && entries.length > 0 ? entries[entries.length - 1].captureSequence : state.currentSequence;
-  return {
-    entries,
-    totalMatched: matched.length,
-    nextCursor: encodeCaptureCursor({
-      tabId: state.tabId,
-      generation: state.generation,
-      sequence: nextSequence,
-      scope
-    }),
-    hasMore,
-    gap: after !== void 0 && afterSequence < droppedThroughSequence
-  };
-}
-
 // src/cdp-backend/domain-manager.ts
 var enabledDomains = /* @__PURE__ */ new WeakMap();
 function ensureCdpDomain(client2, domain2, params = {}) {
@@ -4678,7 +4819,8 @@ function createBuffers(tabId = 0) {
       generation: createCaptureGeneration(),
       currentSequence: 0,
       droppedRequestsThroughSequence: 0,
-      droppedLogsThroughSequence: 0
+      droppedLogsThroughSequence: 0,
+      droppedEventsThroughSequence: 0
     }
   };
 }
@@ -4741,15 +4883,20 @@ function parsePostData(postData) {
     }
   }
 }
-function appendTrackingEvents(buffers, url2, postData, sequence) {
+function appendTrackingEvents(buffers, url2, postData, batchSequence, captureSequence) {
   const events = parseTrackingRequest(url2, postData, {
-    sequence,
+    sequence: batchSequence,
     now: Date.now()
-  });
+  }).map((event) => ({ ...event, captureSequence }));
   if (events.length === 0) return false;
-  buffers.events.push(...events);
-  if (buffers.events.length > MAX_EVENTS) {
-    buffers.events.splice(0, buffers.events.length - MAX_EVENTS);
+  const removed = appendCapturedTrackingBatch(buffers.events, events, MAX_EVENTS);
+  for (const event of removed) {
+    if (event.captureSequence !== void 0) {
+      buffers.capture.droppedEventsThroughSequence = Math.max(
+        buffers.capture.droppedEventsThroughSequence,
+        event.captureSequence
+      );
+    }
   }
   return true;
 }
@@ -4787,10 +4934,19 @@ async function setupBufferListeners(client2, buffers) {
     const url2 = params.request?.url ?? "";
     if (!url2.startsWith("http")) return;
     if (isTrackingUrl(url2)) {
-      const sequence = ++buffers.requestCounter;
-      const captured = appendTrackingEvents(buffers, url2, params.request?.postData, sequence);
+      const batchSequence = ++buffers.requestCounter;
+      const captureSequence2 = nextCaptureSequence(buffers.capture);
+      const captured = appendTrackingEvents(
+        buffers,
+        url2,
+        params.request?.postData,
+        batchSequence,
+        captureSequence2
+      );
       if (!captured && params.request?.hasPostData && !params.request?.postData) {
-        client2.sendCommand("Network.getRequestPostData", { requestId: params.requestId }, 1e4).then((result) => appendTrackingEvents(buffers, url2, result?.postData, sequence)).catch(() => {
+        client2.sendCommand("Network.getRequestPostData", { requestId: params.requestId }, 1e4).then(
+          (result) => appendTrackingEvents(buffers, url2, result?.postData, batchSequence, captureSequence2)
+        ).catch(() => {
         });
       }
       return;
@@ -6590,17 +6746,27 @@ async function collectCdpPageDiagnostics(session, after, diagnostics) {
     };
     result.requests = await cdpGetRequests(session, { ...options, after });
   }
+  if (diagnostics.events) {
+    const options = diagnostics.events === true ? { source: "all", limit: 100 } : { source: "all", limit: 100, ...diagnostics.events };
+    result.events = await cdpGetEvents(session, { ...options, after });
+  }
   return result;
 }
 async function cdpGetEvents(session, data) {
-  const { source = "all", event_type, since, limit = 20, filter, includeRaw = false } = data;
-  const response = queryTrackingEvents(session.buffers.events, {
-    source,
-    event_type,
-    since,
-    limit,
-    filter
-  });
+  const { source = "all", event_type, since, after, limit = 20, filter, includeRaw = false } = data;
+  const response = queryCapturedTrackingEvents(
+    session.buffers.events,
+    session.buffers.capture,
+    {
+      source,
+      event_type,
+      since,
+      after,
+      limit,
+      filter
+    },
+    session.buffers.capture.droppedEventsThroughSequence
+  );
   const captureStatus = response.totalInBuffer === 0 ? "armed" : "active";
   const hint = response.events.length === 0 && captureStatus === "armed" ? TRACKING_CAPTURE_ARMED_HINT : void 0;
   return {
@@ -6612,12 +6778,17 @@ async function cdpGetEvents(session, data) {
       captureStatus,
       captureSource: "cdp",
       includeRaw,
+      after,
+      nextCursor: response.nextCursor,
+      hasMore: response.hasMore,
+      gap: response.gap,
       hint
     },
     events: response.events.map((event) => formatTrackingEvent(event, includeRaw))
   };
 }
 registerActions([
+  { name: "tab_checkpoint", session: "page", handler: cdpCaptureCheckpoint },
   { name: "capture_checkpoint", session: "page", handler: cdpCaptureCheckpoint },
   { name: "get_requests", session: "page", handler: cdpGetRequests },
   { name: "get_logs", session: "page", handler: cdpGetLogs },
@@ -6708,19 +6879,23 @@ async function cdpObservedPageAction(session, action, data, controlSource = "loc
     if (!diagnostics) return dispatchCdpAction(session, action, actionData, controlSource);
     const cursor = captureCheckpoint(pageSession.buffers.capture);
     let actionResult;
-    let actionError;
+    let actionFailure;
     try {
       actionResult = await dispatchCdpAction(session, action, actionData, controlSource);
     } catch (error48) {
-      actionError = error48 instanceof Error ? error48.message : String(error48);
+      actionFailure = describePageActionFailure(error48);
     }
-    return {
+    const result2 = {
       action: {
         name: action,
-        success: actionError === void 0,
+        success: actionFailure === void 0,
         ...actionResult !== void 0 ? { data: actionResult } : {},
-        ...actionError ? { error: actionError } : {}
-      },
+        ...actionFailure ? actionFailure : {}
+      }
+    };
+    if (actionFailure?.stage === "precondition") return result2;
+    return {
+      ...result2,
       diagnostics: await collectCdpPageDiagnostics(pageSession, cursor, diagnostics)
     };
   }
@@ -6744,7 +6919,7 @@ async function cdpObservedPageAction(session, action, data, controlSource = "loc
       disposeObservation: () => disposePageObservation(pageSession)
     }
   );
-  if (!diagnostics || !diagnosticsCursor) return result;
+  if (!diagnostics || !diagnosticsCursor || result.action.stage === "precondition") return result;
   return {
     ...result,
     diagnostics: await collectCdpPageDiagnostics(pageSession, diagnosticsCursor, diagnostics)
@@ -8229,7 +8404,9 @@ var GET_DRAG_COORDS_FROM_NODE_SRC = getDragCoordsFromNode.toString();
 function resolveSnapshotRef(session, ref) {
   const entry = resolvePageRef(session, ref);
   if (!entry) {
-    throw new Error(`Ref ${ref} not found. Run page_snapshot first to get fresh refs.`);
+    throw new PageActionPreconditionError(
+      `Ref ${ref} not found. Run page_snapshot first to get fresh refs.`
+    );
   }
   return entry;
 }
@@ -8264,7 +8441,7 @@ async function clickBySelectorJs(session, selector) {
   });
   const value = result.result?.value;
   if (!value) throw new Error("click evaluation returned no value");
-  if (value.error) throw new Error(value.error);
+  if (value.error) throw new PageActionPreconditionError(value.error);
   return { ...value, dispatchMode: "dom" };
 }
 async function clickByBackendNodeJs(session, backendNodeId) {
@@ -8275,6 +8452,9 @@ async function clickByBackendNodeJs(session, backendNodeId) {
     returnByValue: true
   });
   const value = result.result?.value;
+  if (value === null) {
+    throw new PageActionPreconditionError("Cannot resolve clickable element");
+  }
   if (!value) throw new Error("click evaluation returned no value");
   return {
     tag: value.tag,
@@ -8295,11 +8475,12 @@ async function clickByPointJs(session, point) {
     returnByValue: true
   });
   const value = result.result?.value;
-  if (!value) {
-    throw new Error(
+  if (value === null) {
+    throw new PageActionPreconditionError(
       `page_click: no element found at point (${point.x}, ${point.y}) in the current viewport.`
     );
   }
+  if (!value) throw new Error("click evaluation returned no value");
   return {
     tag: value.tag,
     text: value.text,
@@ -8337,7 +8518,7 @@ async function getElementCoordsBySelector(session, selector) {
   });
   const value = result.result?.value;
   if (!value) throw new Error("coord evaluation returned no value");
-  if (value.error) throw new Error(value.error);
+  if (value.error) throw new PageActionPreconditionError(value.error);
   return value;
 }
 async function getElementCoordsByBackendNodeId(session, backendNodeId) {
@@ -8348,13 +8529,16 @@ async function getElementCoordsByBackendNodeId(session, backendNodeId) {
     returnByValue: true
   });
   const value = result.result?.value;
-  if (!value) {
-    throw new Error(`Cannot resolve clickable element for backendNodeId ${backendNodeId}`);
+  if (value === null) {
+    throw new PageActionPreconditionError(
+      `Cannot resolve clickable element for backendNodeId ${backendNodeId}`
+    );
   }
+  if (!value) throw new Error("coord evaluation returned no value");
   return value;
 }
 async function resolveScopeBackendNodeId(session, scope) {
-  validatePageElementSelector(scope, "page_click scope");
+  checkPageActionPrecondition(() => validatePageElementSelector(scope, "page_click scope"));
   if (scope.startsWith("@e")) {
     return resolveSnapshotRef(session, scope).backendNodeId;
   }
@@ -8364,17 +8548,17 @@ async function resolveScopeBackendNodeId(session, scope) {
   });
   if (evaluated.exceptionDetails) {
     const message = evaluated.exceptionDetails.exception?.description ?? evaluated.exceptionDetails.text ?? "invalid selector";
-    throw new Error(`page_click: invalid scope "${scope}": ${message}`);
+    throw new PageActionPreconditionError(`page_click: invalid scope "${scope}": ${message}`);
   }
   const objectId = evaluated.result?.objectId;
   if (!objectId || evaluated.result?.subtype === "null") {
-    throw new Error(`page_click: scope not found: ${scope}`);
+    throw new PageActionPreconditionError(`page_click: scope not found: ${scope}`);
   }
   try {
     const described = await session.client.sendCommand("DOM.describeNode", { objectId });
     const backendNodeId = described.node?.backendNodeId;
     if (backendNodeId === void 0) {
-      throw new Error(`page_click: cannot resolve scope: ${scope}`);
+      throw new PageActionPreconditionError(`page_click: cannot resolve scope: ${scope}`);
     }
     return backendNodeId;
   } finally {
@@ -8391,21 +8575,28 @@ async function cdpPageClick(session, data) {
     Boolean
   );
   if (clickMode !== void 0 && !["auto", "dom", "mouse", "touch"].includes(clickMode)) {
-    throw new Error('page_click: "clickMode" must be one of auto, dom, mouse, touch');
+    throw new PageActionPreconditionError(
+      'page_click: "clickMode" must be one of auto, dom, mouse, touch'
+    );
   }
   if (scope !== void 0 && !hasText) {
-    throw new Error('page_click: "scope" is only supported with the "text" target');
+    throw new PageActionPreconditionError(
+      'page_click: "scope" is only supported with the "text" target'
+    );
   }
   if (scope !== void 0) {
-    validatePageElementSelector(scope, "page_click scope");
+    checkPageActionPrecondition(() => validatePageElementSelector(scope, "page_click scope"));
+  }
+  if (hasSelector) {
+    checkPageActionPrecondition(() => validatePageElementSelector(selector, "page_click"));
   }
   if (provided.length === 0) {
-    throw new Error(
+    throw new PageActionPreconditionError(
       'page_click: provide exactly one of "selector", "text", or "point". For text matching, pass "text" (and optionally "role"/"exact"). For coordinate clicks, pass "point": { x, y } in viewport pixels.'
     );
   }
   if (provided.length > 1) {
-    throw new Error(
+    throw new PageActionPreconditionError(
       `page_click: provide exactly one of "selector", "text", or "point" — got ${provided.length} (${provided.join(", ")}).`
     );
   }
@@ -8483,13 +8674,13 @@ async function cdpPageClick(session, data) {
     if (hits.length === 0) {
       const exactSuffix = exact === false ? " (substring match)" : "";
       const roleSuffix = role ? ` with role "${role}"` : "";
-      throw new Error(
+      throw new PageActionPreconditionError(
         `page_click: text "${text}"${roleSuffix}${exactSuffix}${scope ? ` in scope "${scope}"` : ""} not found. Run page_snapshot to inspect the page, or try exact: false for substring matching.`
       );
     }
     if (hits.length > 1) {
       const candidates = formatAXTextMatchCandidates(hits);
-      throw new Error(
+      throw new PageActionPreconditionError(
         `page_click: text "${text}"${scope ? ` in scope "${scope}"` : ""} matched ${hits.length} elements. Refine with "role" or "exact: true", or run page_snapshot and use an "@eN" ref:
 ${candidates}`
       );
@@ -8519,7 +8710,7 @@ ${candidates}`
       )
     );
   }
-  if (!point) throw new Error("page_click point is required");
+  if (!point) throw new PageActionPreconditionError("page_click point is required");
   if (effectiveClickMode === "dom") {
     const dispatchTarget = await clickByPointJs(session, point);
     return finalize2(createPageClickResult({ kind: "point", point }, dispatchTarget));
@@ -8608,7 +8799,7 @@ async function resolveDragEndpoint(session, endpoint) {
   };
 }
 async function cdpPageDrag(session, data) {
-  const input = resolvePageDragInput(data);
+  const input = checkPageActionPrecondition(() => resolvePageDragInput(data));
   const visibilityResult = input.dragMode === "auto" ? await session.client.sendCommand("Runtime.evaluate", {
     expression: "document.visibilityState",
     returnByValue: true
@@ -8670,11 +8861,14 @@ async function cdpPageDrag(session, data) {
 async function cdpPageType(session, data) {
   const { selector, text, clearFirst = true } = data;
   if (!selector || typeof selector !== "string") {
-    throw new Error(
+    throw new PageActionPreconditionError(
       `"selector" must be a non-empty string. Pass a native CSS selector (e.g. "[aria-label='提交']") or a snapshot ref like "@e3". Note: the field name is "selector", not "ref".`
     );
   }
-  if (typeof text !== "string") throw new Error('"text" must be a string.');
+  checkPageActionPrecondition(() => validatePageElementSelector(selector, "page_type"));
+  if (typeof text !== "string") {
+    throw new PageActionPreconditionError('"text" must be a string.');
+  }
   if (selector.startsWith("@e")) {
     return withSnapshotRef(session, selector, async (entry) => {
       const objectId = await resolveBackendNodeObjectId(session, entry.backendNodeId);
@@ -8688,7 +8882,7 @@ async function cdpPageType(session, data) {
       });
       const value2 = result.result?.value;
       if (!value2) throw new Error("cdp_page_type: evaluation returned no value");
-      if (value2.error) throw new Error(value2.error);
+      if (value2.error) throw new PageActionPreconditionError(value2.error);
       return { typed: true, tag: value2.tag };
     });
   }
@@ -8706,12 +8900,12 @@ async function cdpPageType(session, data) {
   });
   const value = r.result?.value;
   if (!value) throw new Error("cdp_page_type: evaluation returned no value");
-  if (value.error) throw new Error(value.error);
-  if (!value.typed) throw new Error("cdp_page_type: failed to type");
+  if (value.error) throw new PageActionPreconditionError(value.error);
+  if (!value.typed) throw new PageActionPreconditionError("cdp_page_type: failed to type");
   return { typed: true, tag: value.tag };
 }
 async function cdpPageScroll(session, data) {
-  const input = resolvePageScrollInput(data ?? {});
+  const input = checkPageActionPrecondition(() => resolvePageScrollInput(data ?? {}));
   if (input.selector?.startsWith("@e")) {
     return withSnapshotRef(session, input.selector, async (entry) => {
       const objectId = await resolveBackendNodeObjectId(session, entry.backendNodeId);
@@ -8749,7 +8943,7 @@ async function cdpPageScroll(session, data) {
 async function cdpPageEval(session, data) {
   const { expression, awaitPromise = true } = data;
   if (!expression || typeof expression !== "string") {
-    throw new Error("Invalid expression");
+    throw new PageActionPreconditionError("Invalid expression");
   }
   const result = await session.client.sendCommand("Runtime.evaluate", {
     expression,
@@ -8765,7 +8959,7 @@ async function cdpPageEval(session, data) {
 }
 async function cdpPagePress(session, data) {
   const { key } = data;
-  if (!key || typeof key !== "string") throw new Error("Invalid key");
+  if (!key || typeof key !== "string") throw new PageActionPreconditionError("Invalid key");
   await session.client.sendCommand("Input.dispatchKeyEvent", {
     type: "keyDown",
     key
@@ -8883,10 +9077,15 @@ async function waitForHistoryIndex(session, targetIndex, timeoutMs) {
 async function cdpPageUpload(session, data) {
   const { selector, filePaths } = data ?? {};
   if (typeof selector !== "string" || selector.length === 0) {
-    throw new Error('page_upload: "selector" is required (CSS selector or @eN snapshot ref)');
+    throw new PageActionPreconditionError(
+      'page_upload: "selector" is required (CSS selector or @eN snapshot ref)'
+    );
   }
+  checkPageActionPrecondition(() => validatePageElementSelector(selector, "page_upload"));
   if (!Array.isArray(filePaths) || filePaths.length === 0 || filePaths.some((filePath) => typeof filePath !== "string" || filePath.length === 0)) {
-    throw new Error("Invalid filePaths: must be a non-empty array of file path strings");
+    throw new PageActionPreconditionError(
+      "Invalid filePaths: must be a non-empty array of file path strings"
+    );
   }
   let described;
   if (selector.startsWith("@e")) {
@@ -8903,16 +9102,20 @@ async function cdpPageUpload(session, data) {
       nodeId: documentResult.root?.nodeId,
       selector
     });
-    if (!queryResult.nodeId) throw new Error(`Element not found: ${selector}`);
+    if (!queryResult.nodeId) {
+      throw new PageActionPreconditionError(`Element not found: ${selector}`);
+    }
     described = await session.client.sendCommand("DOM.describeNode", {
       nodeId: queryResult.nodeId
     });
   }
   const backendNodeId = described.node?.backendNodeId;
   const tag = String(described.node?.nodeName ?? "").toLowerCase();
-  if (backendNodeId === void 0) throw new Error(`Cannot resolve file input: ${selector}`);
+  if (backendNodeId === void 0) {
+    throw new PageActionPreconditionError(`Cannot resolve file input: ${selector}`);
+  }
   if (tag !== "input") {
-    throw new Error(
+    throw new PageActionPreconditionError(
       `Element <${tag || "unknown"}> is not a file input. selector must point to an <input type="file"> element.`
     );
   }
@@ -8971,8 +9174,11 @@ async function cdpSetDeviceEmulation(session, data) {
 async function cdpPageHover(session, data) {
   const { selector } = data ?? {};
   if (typeof selector !== "string" || selector.length === 0) {
-    throw new Error('page_hover: "selector" is required (CSS selector or @eN snapshot ref)');
+    throw new PageActionPreconditionError(
+      'page_hover: "selector" is required (CSS selector or @eN snapshot ref)'
+    );
   }
+  checkPageActionPrecondition(() => validatePageElementSelector(selector, "page_hover"));
   const coord = selector.startsWith("@e") ? await withSnapshotRef(
     session,
     selector,
@@ -10239,6 +10445,11 @@ async function requireSessionFromClient(agentBay, sessionId) {
   }
   return result.session;
 }
+async function getAgentBaySession(sessionId, dependencies = {}) {
+  const apiKey = (dependencies.resolveApiKey ?? resolveAgentBayApiKey)();
+  const agentBay = dependencies.createAgentBayClient ? await dependencies.createAgentBayClient(apiKey) : await createClient(apiKey);
+  return requireSessionFromClient(agentBay, sessionId);
+}
 async function getAgentBayAccessUrl(sessionId, dependencies = {}) {
   const apiKey = (dependencies.resolveApiKey ?? resolveAgentBayApiKey)();
   const agentBay = dependencies.createAgentBayClient ? await dependencies.createAgentBayClient(apiKey) : await createClient(apiKey);
@@ -10592,6 +10803,83 @@ async function closeAgentBayBrowser(selector, options = {}) {
   }
 }
 
+// src/agentbay-file-upload.ts
+import { randomUUID as randomUUID4 } from "node:crypto";
+import { basename as basename2, posix } from "node:path";
+var AGENTBAY_FILE_UPLOAD_WAIT_SECONDS = 120;
+function pageUploadTargets(action, data) {
+  if (action === "page_upload") return [{ data }];
+  if (action !== "run_actions" || !Array.isArray(data?.actions)) return [];
+  return data.actions.flatMap(
+    (step, index) => step?.action === "page_upload" ? [{ data: step.data, step: index }] : []
+  );
+}
+function validateFilePaths(target) {
+  const filePaths = target.data?.filePaths;
+  if (!Array.isArray(filePaths) || filePaths.length === 0 || filePaths.some((filePath) => typeof filePath !== "string" || filePath.length === 0)) {
+    const prefix = target.step === void 0 ? "" : `Step ${target.step}: `;
+    throw new Error(`${prefix}Invalid filePaths: must be a non-empty array of file path strings`);
+  }
+  return filePaths;
+}
+function uploadError(result) {
+  return result.errorMessage ?? result.error_message ?? result.error ?? "unknown error";
+}
+async function stageAgentBayPageUploads(sessionId, action, data, dependencies = {}) {
+  const targets = pageUploadTargets(action, data);
+  if (targets.length === 0) return data;
+  const targetFilePaths = targets.map((target) => validateFilePaths(target));
+  const session = await (dependencies.getSession ?? getAgentBaySession)(sessionId);
+  const fileSystem = session.fileSystem;
+  if (!fileSystem) {
+    throw new Error("The installed AgentBay SDK does not support session file transfer");
+  }
+  const contextPath = await fileSystem.getFileTransferContextPath();
+  if (!contextPath) {
+    throw new Error(`AgentBay file transfer context is unavailable for session ${sessionId}`);
+  }
+  const createTransferId = dependencies.createTransferId ?? randomUUID4;
+  const stagedPaths = await Promise.all(
+    targetFilePaths.map(
+      (filePaths) => Promise.all(
+        filePaths.map(async (localPath) => {
+          const remoteDirectory = posix.join(contextPath, createTransferId());
+          const directoryResult = await fileSystem.createDirectory(remoteDirectory);
+          if (directoryResult?.success === false) {
+            throw new Error(
+              `Failed to prepare AgentBay upload for ${basename2(localPath)}: ${uploadError(directoryResult)}`
+            );
+          }
+          const remotePath = posix.join(remoteDirectory, basename2(localPath));
+          const result = await fileSystem.uploadFile(localPath, remotePath, {
+            wait: true,
+            waitTimeout: AGENTBAY_FILE_UPLOAD_WAIT_SECONDS
+          });
+          if (result?.success !== true) {
+            throw new Error(
+              `Failed to upload ${basename2(localPath)} to AgentBay: ${uploadError(result)}`
+            );
+          }
+          return remotePath;
+        })
+      )
+    )
+  );
+  if (action === "page_upload") {
+    return { ...data, filePaths: stagedPaths[0] };
+  }
+  const runActions = data;
+  let targetIndex = 0;
+  return {
+    ...runActions,
+    actions: runActions.actions.map((step) => {
+      if (step.action !== "page_upload") return step;
+      const filePaths = stagedPaths[targetIndex++];
+      return { ...step, data: { ...step.data, filePaths } };
+    })
+  };
+}
+
 // src/browser-registry.ts
 var BROWSERS_SUBDIR = "browsers";
 var STALE_RECORD_TTL_MS = 5 * 6e4;
@@ -10785,10 +11073,10 @@ function listBrowserInventory() {
 import fs3 from "node:fs";
 import path3 from "node:path";
 import os2 from "node:os";
-import { randomUUID as randomUUID4 } from "node:crypto";
+import { randomUUID as randomUUID5 } from "node:crypto";
 
 // src/version.ts
-var NATIVE_HOST_VERSION = true ? "2.7.1" : "unknown";
+var NATIVE_HOST_VERSION = true ? "2.7.2" : "unknown";
 
 // src/analytics.ts
 var MEASUREMENT_ID = "G-W84LJDZ6PH";
@@ -10813,7 +11101,7 @@ function writeConfig(config2) {
   }
 }
 var clientId = null;
-function createClientId(seed = randomUUID4()) {
+function createClientId(seed = randomUUID5()) {
   let first = 2166136261;
   let second = 2246822519;
   for (let index = 0; index < seed.length; index++) {
@@ -32061,11 +32349,6 @@ async function handleViaCdp(action, data, _timeoutMs, controlSource) {
       `${action} requires the Mearl browser extension. Install it from https://chromewebstore.google.com/detail/mearl/aoehhjnofngknnjefamjbplchbolghkm`
     );
   }
-  if (AGENTBAY_SESSION_ID && action === "page_upload") {
-    throw new Error(
-      "page_upload is not available for AgentBay CDP sessions because file paths resolve on the remote browser host."
-    );
-  }
   const available = AGENTBAY_SESSION_ID ? await getCdpSession().getBrowserClient().then(
     () => true,
     () => false
@@ -32080,10 +32363,11 @@ async function handleViaCdp(action, data, _timeoutMs, controlSource) {
       `Chrome DevTools remote debugging is not available on port ${CDP_PORT}. Enable it via chrome://inspect/#remote-debugging (Chrome 145+) or install the Mearl extension.`
     );
   }
-  if (shouldObservePageAction(action, data)) {
-    return cdpObservedPageAction(getCdpSession(), action, data, controlSource);
+  const actionData = AGENTBAY_SESSION_ID ? await stageAgentBayPageUploads(AGENTBAY_SESSION_ID, action, data) : data;
+  if (shouldObservePageAction(action, actionData)) {
+    return cdpObservedPageAction(getCdpSession(), action, actionData, controlSource);
   }
-  return dispatchCdpAction(getCdpSession(), action, data, controlSource);
+  return dispatchCdpAction(getCdpSession(), action, actionData, controlSource);
 }
 function onSocketConnection(socket) {
   let buffer = "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/native-host",
-  "version": "2.7.1",
+  "version": "2.7.2",
   "description": "Native Messaging Host for Mearl — bridges Chrome Extension and local socket server",
   "type": "module",
   "main": "dist/install.js",
@@ -37,9 +37,9 @@
     "@types/ws": "^8.18.1",
     "esbuild": "^0.25.2",
     "typescript": "^5.8.3",
-    "@mearl/browser-core": "2.7.1",
-    "@mearl/daemon-core": "2.7.1",
-    "@mearl/setup": "2.7.1"
+    "@mearl/browser-core": "2.7.2",
+    "@mearl/daemon-core": "2.7.2",
+    "@mearl/setup": "2.7.2"
   },
   "scripts": {
     "build": "rm -rf dist/ && node build.mjs",