opensteer 0.9.5 → 0.9.7

package/dist/index.cjs

@@ -102,6 +102,11 @@ function stableJsonString(value) {
 
 // ../runtime-core/src/internal/filesystem.ts
 var LOCK_RETRY_DELAYS_MS = [1, 2, 5, 10, 20, 50];
+var LOCK_METADATA_FILENAME = "owner.json";
+var LOCK_METADATA_VERSION = 1;
+var LOCK_HEARTBEAT_INTERVAL_MS = 1e3;
+var LOCK_ORPHAN_GRACE_MS = 2e3;
+var LOCK_METADATALESS_STALE_MS = 3e4;
 function normalizeNonEmptyString(name, value) {
   const normalized = value.trim();
   if (normalized.length === 0) {
@@ -207,24 +212,119 @@ function isAlreadyExistsError(error) {
 }
 async function withFilesystemLock(lockPath, task) {
   await ensureDirectory(path10__default.default.dirname(lockPath));
+  const ownerToken = crypto.randomUUID();
   let attempt = 0;
   while (true) {
     try {
       await promises.mkdir(lockPath);
+      const acquiredAt = Date.now();
+      await writeLockMetadata(lockPath, {
+        version: LOCK_METADATA_VERSION,
+        ownerToken,
+        pid: process.pid,
+        acquiredAt,
+        heartbeatAt: acquiredAt
+      });
       break;
     } catch (error) {
       if (!isAlreadyExistsError(error)) {
         throw error;
       }
+      if (await tryRecoverFilesystemLock(lockPath)) {
+        attempt = 0;
+        continue;
+      }
       const delayMs = LOCK_RETRY_DELAYS_MS[Math.min(attempt, LOCK_RETRY_DELAYS_MS.length - 1)];
       attempt += 1;
       await new Promise((resolve4) => setTimeout(resolve4, delayMs));
     }
   }
+  const heartbeatTimer = setInterval(() => {
+    void touchLockMetadata(lockPath, ownerToken);
+  }, LOCK_HEARTBEAT_INTERVAL_MS);
+  heartbeatTimer.unref?.();
   try {
     return await task();
   } finally {
-    await promises.rm(lockPath, { recursive: true, force: true });
+    clearInterval(heartbeatTimer);
+    const metadata = await readLockMetadata(lockPath);
+    if (metadata?.ownerToken === ownerToken) {
+      await promises.rm(lockPath, { recursive: true, force: true });
+    }
+  }
+}
+async function tryRecoverFilesystemLock(lockPath) {
+  if (!await shouldRecoverFilesystemLock(lockPath)) {
+    return false;
+  }
+  await promises.rm(lockPath, { recursive: true, force: true });
+  return true;
+}
+async function shouldRecoverFilesystemLock(lockPath) {
+  const metadata = await readLockMetadata(lockPath);
+  if (metadata !== void 0) {
+    if (isProcessRunning(metadata.pid)) {
+      return false;
+    }
+    return Date.now() - metadata.heartbeatAt >= LOCK_ORPHAN_GRACE_MS;
+  }
+  const lockStat = await promises.stat(lockPath).catch(() => void 0);
+  if (lockStat === void 0) {
+    return false;
+  }
+  return Date.now() - lockStat.mtimeMs >= LOCK_METADATALESS_STALE_MS;
+}
+async function readLockMetadata(lockPath) {
+  const metadataPath = path10__default.default.join(lockPath, LOCK_METADATA_FILENAME);
+  if (!await pathExists(metadataPath)) {
+    return void 0;
+  }
+  try {
+    const parsed = await readJsonFile(metadataPath);
+    const pid = parsed.pid;
+    const acquiredAt = parsed.acquiredAt;
+    const heartbeatAt = parsed.heartbeatAt;
+    if (parsed.version !== LOCK_METADATA_VERSION || typeof parsed.ownerToken !== "string" || parsed.ownerToken.length === 0 || typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0 || typeof acquiredAt !== "number" || !Number.isFinite(acquiredAt) || typeof heartbeatAt !== "number" || !Number.isFinite(heartbeatAt)) {
+      return void 0;
+    }
+    return {
+      version: LOCK_METADATA_VERSION,
+      ownerToken: parsed.ownerToken,
+      pid,
+      acquiredAt,
+      heartbeatAt
+    };
+  } catch {
+    return void 0;
+  }
+}
+async function writeLockMetadata(lockPath, metadata) {
+  try {
+    await writeJsonFileAtomic(path10__default.default.join(lockPath, LOCK_METADATA_FILENAME), metadata);
+  } catch (error) {
+    await promises.rm(lockPath, { recursive: true, force: true }).catch(() => void 0);
+    throw error;
+  }
+}
+async function touchLockMetadata(lockPath, ownerToken) {
+  const metadata = await readLockMetadata(lockPath);
+  if (metadata === void 0 || metadata.ownerToken !== ownerToken) {
+    return;
+  }
+  await writeJsonFileAtomic(path10__default.default.join(lockPath, LOCK_METADATA_FILENAME), {
+    ...metadata,
+    heartbeatAt: Date.now()
+  }).catch(() => void 0);
+}
+function isProcessRunning(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
   }
 }
 
@@ -814,7 +914,7 @@ function isJsonValueEqual(expected, actual) {
 
 // ../protocol/src/version.ts
 var OPENSTEER_PROTOCOL_NAME = "opensteer";
-var OPENSTEER_PROTOCOL_COMPATIBILITY_REVISION = 2;
+var OPENSTEER_PROTOCOL_COMPATIBILITY_REVISION = 3;
 var OPENSTEER_PROTOCOL_VERSION = `0.${OPENSTEER_PROTOCOL_COMPATIBILITY_REVISION}.0`;
 var OPENSTEER_PROTOCOL_REST_BASE_PATH = `/api/v${OPENSTEER_PROTOCOL_COMPATIBILITY_REVISION}`;
 objectSchema(
@@ -1037,9 +1137,6 @@ function isBrowserCoreError(value) {
   return value instanceof BrowserCoreError;
 }
 
-// ../browser-core/src/cdp-visual-stability.ts
-var DEFAULT_VISUAL_STABILITY_SETTLE_MS = 750;
-
 // ../browser-core/src/post-load-tracker.ts
 var DEFAULT_POST_LOAD_TRACKER_QUIET_WINDOW_MS = 400;
 
@@ -1191,7 +1288,7 @@ var visualViewportSchema = objectSchema(
     required: ["origin", "offsetWithinLayoutViewport", "size"]
   }
 );
-var viewportMetricsSchema = objectSchema(
+objectSchema(
   {
     layoutViewport: layoutViewportSchema,
     visualViewport: visualViewportSchema,
@@ -2642,7 +2739,7 @@ var domSnapshotSchema = objectSchema(
     ]
   }
 );
-var hitTestResultSchema = objectSchema(
+objectSchema(
   {
     inputPoint: pointSchema,
     inputCoordinateSpace: coordinateSpaceSchema,
@@ -4095,39 +4192,14 @@ var opensteerTargetInputSchema = oneOfSchema(
     title: "OpensteerTargetInput"
   }
 );
-var opensteerResolvedTargetSchema = objectSchema(
-  {
-    pageRef: pageRefSchema,
-    frameRef: frameRefSchema,
-    documentRef: documentRefSchema,
-    documentEpoch: documentEpochSchema,
-    nodeRef: nodeRefSchema,
-    tagName: stringSchema(),
-    pathHint: stringSchema(),
-    persist: stringSchema(),
-    selectorUsed: stringSchema()
-  },
-  {
-    title: "OpensteerResolvedTarget",
-    required: [
-      "pageRef",
-      "frameRef",
-      "documentRef",
-      "documentEpoch",
-      "nodeRef",
-      "tagName",
-      "pathHint"
-    ]
-  }
-);
 var opensteerActionResultSchema = objectSchema(
   {
-    target: opensteerResolvedTargetSchema,
-    point: pointSchema
+    tagName: stringSchema({ minLength: 1 }),
+    persist: stringSchema({ minLength: 1 })
   },
   {
     title: "OpensteerActionResult",
-    required: ["target"]
+    required: ["tagName"]
   }
 );
 var opensteerSnapshotCounterSchema = objectSchema(
@@ -4173,16 +4245,14 @@ var opensteerSnapshotCounterSchema = objectSchema(
     ]
   }
 );
-var opensteerSessionStateSchema = objectSchema(
+var opensteerNavigationSummarySchema = objectSchema(
   {
-    sessionRef: sessionRefSchema,
-    pageRef: pageRefSchema,
     url: stringSchema(),
     title: stringSchema()
   },
   {
-    title: "OpensteerSessionState",
-    required: ["sessionRef", "pageRef", "url", "title"]
+    title: "OpensteerNavigationSummary",
+    required: ["url", "title"]
   }
 );
 var opensteerOpenInputSchema = objectSchema(
@@ -4250,6 +4320,17 @@ var opensteerPageCloseOutputSchema = objectSchema(
     required: ["closedPageRef", "pages"]
   }
 );
+var opensteerPageNewOutputSchema = objectSchema(
+  {
+    pageRef: pageRefSchema,
+    url: stringSchema(),
+    title: stringSchema()
+  },
+  {
+    title: "OpensteerPageNewOutput",
+    required: ["pageRef", "url", "title"]
+  }
+);
 var opensteerPageGotoInputSchema = objectSchema(
   {
     url: stringSchema(),
@@ -4636,72 +4717,28 @@ var opensteerComputerExecuteInputSchema = objectSchema(
     required: ["action"]
   }
 );
-var opensteerComputerTracePointSchema = objectSchema(
-  {
-    role: enumSchema(["point", "start", "end"]),
-    point: pointSchema,
-    hitTest: hitTestResultSchema,
-    target: opensteerResolvedTargetSchema
-  },
-  {
-    title: "OpensteerComputerTracePoint",
-    required: ["role", "point"]
-  }
-);
-var opensteerComputerTraceEnrichmentSchema = objectSchema(
-  {
-    points: arraySchema(opensteerComputerTracePointSchema)
-  },
-  {
-    title: "OpensteerComputerTraceEnrichment",
-    required: ["points"]
-  }
-);
-var opensteerComputerExecuteTimingSchema = objectSchema(
+var opensteerScreenshotSummarySchema = objectSchema(
   {
-    actionMs: integerSchema({ minimum: 0 }),
-    waitMs: integerSchema({ minimum: 0 }),
-    totalMs: integerSchema({ minimum: 0 })
-  },
-  {
-    title: "OpensteerComputerExecuteTiming",
-    required: ["actionMs", "waitMs", "totalMs"]
-  }
-);
-var opensteerComputerDisplayScaleSchema = objectSchema(
-  {
-    x: numberSchema({ exclusiveMinimum: 0 }),
-    y: numberSchema({ exclusiveMinimum: 0 })
+    payload: externalBinaryLocationSchema,
+    format: screenshotFormatSchema,
+    size: sizeSchema,
+    coordinateSpace: coordinateSpaceSchema,
+    clip: rectSchema
   },
   {
-    title: "OpensteerComputerDisplayScale",
-    required: ["x", "y"]
+    title: "OpensteerScreenshotSummary",
+    required: ["payload", "format", "size", "coordinateSpace"]
   }
 );
 var opensteerComputerExecuteOutputSchema = objectSchema(
   {
-    action: opensteerComputerActionSchema,
-    pageRef: pageRefSchema,
-    screenshot: screenshotArtifactSchema,
-    displayViewport: viewportMetricsSchema,
-    nativeViewport: viewportMetricsSchema,
-    displayScale: opensteerComputerDisplayScaleSchema,
-    events: arraySchema(opensteerEventSchema),
-    timing: opensteerComputerExecuteTimingSchema,
-    trace: opensteerComputerTraceEnrichmentSchema
+    url: stringSchema(),
+    title: stringSchema(),
+    screenshot: opensteerScreenshotSummarySchema
   },
   {
     title: "OpensteerComputerExecuteOutput",
-    required: [
-      "action",
-      "pageRef",
-      "screenshot",
-      "displayViewport",
-      "nativeViewport",
-      "displayScale",
-      "events",
-      "timing"
-    ]
+    required: ["url", "title", "screenshot"]
   }
 );
 function assertValidSemanticOperationInput(name, input) {
@@ -4727,7 +4764,7 @@ var opensteerSemanticOperationSpecificationsBase = [
     name: "session.open",
     description: "Open or resume the current Opensteer session and primary page.",
     inputSchema: opensteerOpenInputSchema,
-    outputSchema: opensteerSessionStateSchema,
+    outputSchema: opensteerNavigationSummarySchema,
     requiredCapabilities: ["sessions.manage", "pages.manage"],
     resolveRequiredCapabilities: (input) => input.url === void 0 ? ["sessions.manage", "pages.manage"] : ["sessions.manage", "pages.manage", "pages.navigate"]
   }),
@@ -4742,7 +4779,7 @@ var opensteerSemanticOperationSpecificationsBase = [
     name: "page.new",
     description: "Create and optionally navigate a new top-level page in the current session.",
     inputSchema: opensteerPageNewInputSchema,
-    outputSchema: opensteerSessionStateSchema,
+    outputSchema: opensteerPageNewOutputSchema,
     requiredCapabilities: ["pages.manage"],
     resolveRequiredCapabilities: (input) => input.url === void 0 ? ["pages.manage"] : ["pages.manage", "pages.navigate"]
   }),
@@ -4750,7 +4787,7 @@ var opensteerSemanticOperationSpecificationsBase = [
     name: "page.activate",
     description: "Activate an existing top-level page in the current session.",
     inputSchema: opensteerPageActivateInputSchema,
-    outputSchema: opensteerSessionStateSchema,
+    outputSchema: opensteerNavigationSummarySchema,
     requiredCapabilities: ["pages.manage", "inspect.pages"]
   }),
   defineSemanticOperationSpec({
@@ -4764,7 +4801,7 @@ var opensteerSemanticOperationSpecificationsBase = [
     name: "page.goto",
     description: "Navigate the current Opensteer page to a new URL.",
     inputSchema: opensteerPageGotoInputSchema,
-    outputSchema: opensteerSessionStateSchema,
+    outputSchema: opensteerNavigationSummarySchema,
     requiredCapabilities: ["pages.navigate"]
   }),
   defineSemanticOperationSpec({
@@ -6845,30 +6882,15 @@ var DEFAULT_SETTLE_DELAYS = {
   "dom-action": 100,
   snapshot: 0
 };
-var defaultSnapshotSettleObserver = {
-  async settle(input) {
-    if (input.trigger !== "snapshot") {
-      return false;
-    }
-    await input.engine.waitForVisualStability({
-      pageRef: input.pageRef,
-      ...input.remainingMs === void 0 ? {} : { timeoutMs: input.remainingMs },
-      settleMs: DEFAULT_VISUAL_STABILITY_SETTLE_MS,
-      scope: "visible-frames"
-    });
-    return true;
-  }
-};
-Object.freeze(defaultSnapshotSettleObserver);
 var DOM_ACTION_VISUAL_STABILITY_PROFILES = {
-  "dom.click": { settleMs: 750, scope: "visible-frames", timeoutMs: 7e3 },
-  "dom.input": { settleMs: 750, scope: "visible-frames", timeoutMs: 7e3 },
-  "dom.scroll": { settleMs: 600, scope: "visible-frames", timeoutMs: 7e3 },
+  "dom.click": { settleMs: 750, scope: "main-frame", timeoutMs: 7e3 },
+  "dom.input": { settleMs: 750, scope: "main-frame", timeoutMs: 7e3 },
+  "dom.scroll": { settleMs: 600, scope: "main-frame", timeoutMs: 7e3 },
   "dom.hover": { settleMs: 200, scope: "main-frame", timeoutMs: 2500 }
 };
 var DEFAULT_DOM_ACTION_VISUAL_STABILITY_PROFILE = {
   settleMs: 750,
-  scope: "visible-frames",
+  scope: "main-frame",
   timeoutMs: 7e3
 };
 var NAVIGATION_VISUAL_STABILITY_PROFILE = {
@@ -6892,6 +6914,7 @@ var defaultDomActionSettleObserver = {
         pageRef: input.pageRef,
         timeoutMs: effectiveTimeout,
         settleMs: profile.settleMs,
+        ...input.observedMutationQuietMs === void 0 ? {} : { initialQuietMs: input.observedMutationQuietMs },
         scope: profile.scope
       });
       return true;
@@ -6912,15 +6935,20 @@ var defaultNavigationSettleObserver = {
       return false;
     }
     try {
-      const startedAt = Date.now();
-      await input.engine.waitForPostLoadQuiet({
-        pageRef: input.pageRef,
-        timeoutMs: effectiveTimeout,
-        quietMs: DEFAULT_POST_LOAD_TRACKER_QUIET_WINDOW_MS,
-        captureWindowMs: Math.min(NAVIGATION_POST_LOAD_CAPTURE_WINDOW_MS, effectiveTimeout),
-        signal: input.signal
-      });
-      const visualTimeout = Math.max(0, effectiveTimeout - (Date.now() - startedAt));
+      let visualTimeout = effectiveTimeout;
+      let initialQuietMs = input.observedMutationQuietMs ?? 0;
+      if (!input.postLoadHandled) {
+        const startedAt = Date.now();
+        await input.engine.waitForPostLoadQuiet({
+          pageRef: input.pageRef,
+          timeoutMs: effectiveTimeout,
+          quietMs: DEFAULT_POST_LOAD_TRACKER_QUIET_WINDOW_MS,
+          captureWindowMs: Math.min(NAVIGATION_POST_LOAD_CAPTURE_WINDOW_MS, effectiveTimeout),
+          signal: input.signal
+        });
+        visualTimeout = Math.max(0, effectiveTimeout - (Date.now() - startedAt));
+        initialQuietMs = Math.max(initialQuietMs, DEFAULT_POST_LOAD_TRACKER_QUIET_WINDOW_MS);
+      }
       if (visualTimeout <= 0) {
         return true;
       }
@@ -6928,6 +6956,7 @@ var defaultNavigationSettleObserver = {
         pageRef: input.pageRef,
         timeoutMs: visualTimeout,
         settleMs: profile.settleMs,
+        ...initialQuietMs <= 0 ? {} : { initialQuietMs },
         scope: profile.scope
       });
       return true;
@@ -6938,7 +6967,6 @@ var defaultNavigationSettleObserver = {
 };
 Object.freeze(defaultNavigationSettleObserver);
 var DEFAULT_SETTLE_OBSERVERS = Object.freeze([
-  defaultSnapshotSettleObserver,
   defaultDomActionSettleObserver,
   defaultNavigationSettleObserver
 ]);
@@ -7391,6 +7419,9 @@ function buildClauseSelector(node, clause) {
   if (!clause || typeof clause !== "object") {
     return "";
   }
+  if (clause.kind === "text") {
+    return "";
+  }
   if (clause.kind === "position") {
     if (clause.axis === "nthOfType") {
       return `:nth-of-type(${Math.max(1, Number(node.position?.nthOfType || 1))})`;
@@ -7515,7 +7546,7 @@ function resolveExtractedValueInContext(normalizedValue, options) {
 function stripPositionClauses(nodes) {
   return (nodes || []).map((node) => ({
     ...node,
-    match: (node.match || []).filter((clause) => clause.kind !== "position")
+    match: (node.match || []).filter((clause) => clause.kind !== "position" && clause.kind !== "text")
   }));
 }
 function dedupeSelectors(selectors) {
@@ -8092,9 +8123,17 @@ function resolveDomPathInScope(index, domPath, scope) {
   if (!candidates.length) {
     return null;
   }
+  const lastNode = domPath[domPath.length - 1];
+  const textClauses = lastNode?.match.filter((c) => c.kind === "text") ?? [];
   let fallback = null;
   for (const selector of candidates) {
-    const matches = querySelectorAllInScope(index, selector, scope);
+    let matches = querySelectorAllInScope(index, selector, scope);
+    if (textClauses.length > 0 && matches.length > 1) {
+      const filtered = matches.filter((node) => matchesTextClauses(node, textClauses));
+      if (filtered.length > 0) {
+        matches = filtered;
+      }
+    }
     if (matches.length === 1) {
       return {
         node: matches[0],
@@ -8114,6 +8153,10 @@ function resolveDomPathInScope(index, domPath, scope) {
   }
   return fallback;
 }
+function matchesTextClauses(node, clauses) {
+  const text = (node.textContent ?? "").replace(/\s+/g, " ").trim();
+  return clauses.every((clause) => text.includes(clause.value));
+}
 function queryAllDomPathInScope(index, domPath, scope) {
   const selectors = buildPathCandidates(domPath);
   for (const selector of selectors) {
@@ -8272,7 +8315,13 @@ function clonePathNode(node) {
   };
 }
 function cloneMatchClause(clause) {
-  return clause.kind === "position" ? { kind: "position", axis: clause.axis } : {
+  if (clause.kind === "position") {
+    return { kind: "position", axis: clause.axis };
+  }
+  if (clause.kind === "text") {
+    return { kind: "text", value: clause.value };
+  }
+  return {
     kind: "attr",
     key: clause.key,
     ...clause.op === void 0 ? {} : { op: clause.op },
@@ -8327,6 +8376,13 @@ function normalizeMatch(rawMatch, attrs, position, tag) {
           op,
           ...value === void 0 ? {} : { value }
         });
+        continue;
+      }
+      if (record.kind === "text") {
+        const textValue = typeof record.value === "string" ? record.value.trim() : "";
+        if (textValue) {
+          push({ kind: "text", value: textValue.slice(0, 80) });
+        }
       }
     }
   }
@@ -8694,7 +8750,7 @@ function isTimeoutError(error) {
 }
 
 // ../runtime-core/src/runtimes/dom/executor.ts
-var MAX_DOM_ACTION_ATTEMPTS = 3;
+var MAX_DOM_ACTION_ATTEMPTS = 2;
 var DEFAULT_SCROLL_OPTIONS = {
   block: "center",
   inline: "center"
@@ -8984,7 +9040,7 @@ var DomActionExecutor = class {
         ...snapshot === void 0 ? {} : { snapshot },
         signal: timeout.signal,
         remainingMs: () => timeout.remainingMs(),
-        policySettle: async (targetPageRef, trigger) => {
+        policySettle: async (targetPageRef, trigger, boundary2) => {
           try {
             await settleWithPolicy(this.options.policy.settle, {
               operation,
@@ -8992,7 +9048,9 @@ var DomActionExecutor = class {
               engine: this.options.engine,
               pageRef: targetPageRef,
               signal: timeout.signal,
-              remainingMs: timeout.remainingMs()
+              remainingMs: timeout.remainingMs(),
+              ...boundary2?.observedMutationQuietMs === void 0 ? {} : { observedMutationQuietMs: boundary2.observedMutationQuietMs },
+              ...boundary2?.postLoadHandled === true ? { postLoadHandled: true } : {}
             });
           } catch (error) {
             if (snapshot !== void 0 && isSoftSettleTimeoutError(error, timeout.signal)) {
@@ -9181,11 +9239,12 @@ var DomActionExecutor = class {
     throw this.createActionabilityError(
       operation,
       "obscured",
-      `hit test resolved ${hit.nodeRef} outside the target subtree rooted at ${resolved.nodeRef}`,
+      `target is obscured by ${assessment.blockingDescription ?? "another element"} at the click point`,
       {
         ...details,
         hitRelation: assessment.relation,
         ...assessment.ambiguous === void 0 ? {} : { hitAmbiguous: assessment.ambiguous },
+        ...assessment.blockingDescription === void 0 ? {} : { blockingDescription: assessment.blockingDescription },
         ...assessment.canonicalTarget === void 0 ? {} : {
           canonicalNodeRef: assessment.canonicalTarget.nodeRef,
           canonicalDocumentRef: assessment.canonicalTarget.documentRef,
@@ -9199,8 +9258,7 @@ var DomActionExecutor = class {
         hitMissingFromSnapshot: !resolved.snapshot.nodes.some(
           (node) => node.nodeRef === hit.nodeRef
         )
-      },
-      true
+      }
     );
   }
   async resolveActionablePointerTarget(session, operation, resolved) {
@@ -9412,7 +9470,12 @@ var DefaultDomRuntime = class {
     });
   }
   async buildPath(input) {
-    return sanitizeReplayElementPath(await this.requireBridge().buildReplayPath(input.locator));
+    return sanitizeReplayElementPath(
+      await this.requireBridge().buildReplayPath(
+        input.locator,
+        input.enableTextMatch ? { enableTextMatch: true } : void 0
+      )
+    );
   }
   async resolveTarget(input) {
     return this.withSnapshotSession((session) => this.resolveTargetWithSession(session, input));
@@ -9632,7 +9695,7 @@ var DefaultDomRuntime = class {
     if (resolvedByLocator) {
       const { snapshot, node } = resolvedByLocator;
       const anchor = await this.buildAnchorFromSnapshotNode(session, snapshot, node);
-      const replayPath = await this.tryBuildPathFromNode(snapshot, node);
+      const replayPath = await this.tryBuildPathFromNode(snapshot, node, { enableTextMatch: true });
       return this.createResolvedTarget("live", snapshot, node, anchor, {
         ...target.persist === void 0 ? {} : { persist: target.persist },
         ...replayPath === void 0 ? {} : { replayPath }
@@ -9650,11 +9713,12 @@ var DefaultDomRuntime = class {
     const { snapshot, node } = resolved;
     const anchor = await this.buildAnchorFromSnapshotNode(session, snapshot, node);
     const writeDescriptor = descriptorWriter ?? ((input) => this.descriptors.write(input));
-    const replayPath = await this.tryBuildPathFromNode(snapshot, node);
+    const enableTextMatch = method !== "extract";
+    const replayPath = await this.tryBuildPathFromNode(snapshot, node, { enableTextMatch });
     const descriptor = target.persist === void 0 ? void 0 : await writeDescriptor({
       method,
       persist: target.persist,
-      path: replayPath ?? await this.buildPathForNode(snapshot, node),
+      path: replayPath ?? await this.buildPathForNode(snapshot, node, { enableTextMatch }),
       sourceUrl: snapshot.url
     });
     return this.createResolvedTarget("selector", snapshot, node, anchor, {
@@ -9754,7 +9818,7 @@ var DefaultDomRuntime = class {
         `Unable to resolve structural anchor "${buildPathSelectorHint(anchor)}" in the current session`
       );
     }
-    const replayPath = await this.tryBuildPathFromNode(context.snapshot, target.node);
+    const replayPath = await this.tryBuildPathFromNode(context.snapshot, target.node, { enableTextMatch: true });
     return this.createResolvedTarget(source, context.snapshot, target.node, anchor, {
       ...persist === void 0 ? {} : { persist },
       ...replayPath === void 0 ? {} : { replayPath }
@@ -9925,19 +9989,20 @@ var DefaultDomRuntime = class {
     }
     return this.bridge;
   }
-  async buildPathForNode(snapshot, node) {
+  async buildPathForNode(snapshot, node, options) {
     if (node.nodeRef === void 0) {
       throw new Error(
         `snapshot node ${String(node.snapshotNodeId)} does not expose a live node reference`
       );
     }
     return this.buildPath({
-      locator: createNodeLocator(snapshot.documentRef, snapshot.documentEpoch, node.nodeRef)
+      locator: createNodeLocator(snapshot.documentRef, snapshot.documentEpoch, node.nodeRef),
+      ...options?.enableTextMatch ? { enableTextMatch: true } : {}
     });
   }
-  async tryBuildPathFromNode(snapshot, node) {
+  async tryBuildPathFromNode(snapshot, node, options) {
     try {
-      return await this.buildPathForNode(snapshot, node);
+      return await this.buildPathForNode(snapshot, node, options);
     } catch {
       return void 0;
     }
@@ -10373,29 +10438,29 @@ function buildVariantDescriptorFromCluster(descriptors) {
   const keyStats = /* @__PURE__ */ new Map();
   for (const descriptor of descriptors) {
     for (const field of descriptor.fields) {
-      const stat2 = keyStats.get(field.path) ?? {
+      const stat3 = keyStats.get(field.path) ?? {
         indices: /* @__PURE__ */ new Set(),
         pathNodes: [],
         attributes: [],
         sources: []
       };
-      stat2.indices.add(descriptor.index);
+      stat3.indices.add(descriptor.index);
       if (isPersistedOpensteerExtractionValueNode(field.node)) {
-        stat2.pathNodes.push(field.node.$path);
-        stat2.attributes.push(field.node.attribute);
+        stat3.pathNodes.push(field.node.$path);
+        stat3.attributes.push(field.node.attribute);
       } else if (isPersistedOpensteerExtractionSourceNode(field.node)) {
-        stat2.sources.push("current_url");
+        stat3.sources.push("current_url");
       }
-      keyStats.set(field.path, stat2);
+      keyStats.set(field.path, stat3);
     }
   }
   const mergedFields = [];
-  for (const [fieldPath, stat2] of keyStats) {
-    if (stat2.indices.size < threshold) {
+  for (const [fieldPath, stat3] of keyStats) {
+    if (stat3.indices.size < threshold) {
       continue;
     }
-    if (stat2.pathNodes.length >= threshold) {
-      let mergedFieldPath = stat2.pathNodes.length === 1 ? sanitizeElementPath(stat2.pathNodes[0]) : mergeElementPathsByMajority(stat2.pathNodes);
+    if (stat3.pathNodes.length >= threshold) {
+      let mergedFieldPath = stat3.pathNodes.length === 1 ? sanitizeElementPath(stat3.pathNodes[0]) : mergeElementPathsByMajority(stat3.pathNodes);
       if (!mergedFieldPath) {
         continue;
       }
@@ -10403,8 +10468,8 @@ function buildVariantDescriptorFromCluster(descriptors) {
         mergedFieldPath = relaxPathForSingleSample(mergedFieldPath, "field");
       }
       mergedFieldPath = minimizePathMatchClauses(mergedFieldPath, "field");
-      const attrThreshold = stat2.pathNodes.length === 1 ? 1 : majorityThreshold(stat2.pathNodes.length);
-      const attribute = pickModeString(stat2.attributes, attrThreshold);
+      const attrThreshold = stat3.pathNodes.length === 1 ? 1 : majorityThreshold(stat3.pathNodes.length);
+      const attribute = pickModeString(stat3.attributes, attrThreshold);
       mergedFields.push({
         path: fieldPath,
         node: createValueNode({
@@ -10414,7 +10479,7 @@ function buildVariantDescriptorFromCluster(descriptors) {
       });
       continue;
     }
-    const dominantSource = pickModeString(stat2.sources, threshold);
+    const dominantSource = pickModeString(stat3.sources, threshold);
     if (dominantSource === "current_url") {
       mergedFields.push({
         path: fieldPath,
@@ -10551,6 +10616,9 @@ function relaxPathForSingleSample(path18, mode) {
         }
         return !isLast;
       }
+      if (clause.kind === "text") {
+        return false;
+      }
       const key = String(clause.key || "").trim().toLowerCase();
       if (!key || !shouldKeepAttrForSingleSample(key)) {
         return false;
@@ -10653,9 +10721,11 @@ function buildNodeStructure(node) {
     }
     structuralAttrs[key] = value;
   }
-  const matchClauses = (node.match || []).map(
-    (clause) => clause.kind === "position" ? `position:${clause.axis}` : `attr:${String(clause.key || "").trim().toLowerCase()}`
-  ).sort();
+  const matchClauses = (node.match || []).map((clause) => {
+    if (clause.kind === "position") return `position:${clause.axis}`;
+    if (clause.kind === "text") return `text:${clause.value}`;
+    return `attr:${String(clause.key || "").trim().toLowerCase()}`;
+  }).sort();
   return {
     tag,
     attrs: structuralAttrs,
@@ -11061,6 +11131,9 @@ function mergeMatchByMajority(matchLists, attrs, threshold, positionFlags = {
       });
       continue;
     }
+    if (clause.kind === "text") {
+      continue;
+    }
     if (clause.axis === "nthOfType") {
       if (positionFlags.hasNthOfType) {
         merged.push({ kind: "position", axis: "nthOfType" });
@@ -11989,9 +12062,9 @@ async function getProcessLiveness(owner) {
   if (typeof startedAtMs === "number") {
     return hasMatchingProcessStartTime(owner.processStartedAtMs, startedAtMs) ? "live" : "dead";
   }
-  return isProcessRunning(owner.pid) ? "unknown" : "dead";
+  return isProcessRunning2(owner.pid) ? "unknown" : "dead";
 }
-function isProcessRunning(pid) {
+function isProcessRunning2(pid) {
   try {
     process.kill(pid, 0);
     return true;
@@ -13411,11 +13484,31 @@ async function writePersistedSessionRecord(rootPath, record) {
 async function clearPersistedSessionRecord(rootPath, provider) {
   await promises.rm(resolveLiveSessionRecordPath(rootPath, provider), { force: true });
 }
+function getPersistedLocalBrowserSessionOwnership(record) {
+  return record.ownership === "attached" ? "attached" : "owned";
+}
+async function isAttachedLocalBrowserSessionReachable(record) {
+  if (getPersistedLocalBrowserSessionOwnership(record) !== "attached") {
+    return false;
+  }
+  if (record.engine !== "playwright" || record.endpoint === void 0) {
+    return false;
+  }
+  try {
+    await inspectCdpEndpoint({
+      endpoint: record.endpoint,
+      timeoutMs: 1500
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
 function isPersistedCloudSessionRecord(value) {
   return value.layout === OPENSTEER_LIVE_SESSION_LAYOUT && value.version === OPENSTEER_LIVE_SESSION_VERSION && value.provider === "cloud" && typeof value.sessionId === "string" && value.sessionId.length > 0 && typeof value.startedAt === "number" && Number.isFinite(value.startedAt) && typeof value.updatedAt === "number" && Number.isFinite(value.updatedAt);
 }
 function isPersistedLocalBrowserSessionRecord(value) {
-  return value.layout === OPENSTEER_LIVE_SESSION_LAYOUT && value.version === OPENSTEER_LIVE_SESSION_VERSION && value.provider === "local" && (value.engine === "playwright" || value.engine === "abp") && typeof value.pid === "number" && Number.isFinite(value.pid) && typeof value.startedAt === "number" && Number.isFinite(value.startedAt) && typeof value.updatedAt === "number" && Number.isFinite(value.updatedAt) && typeof value.userDataDir === "string" && value.userDataDir.length > 0;
+  return value.layout === OPENSTEER_LIVE_SESSION_LAYOUT && value.version === OPENSTEER_LIVE_SESSION_VERSION && value.provider === "local" && (value.engine === "playwright" || value.engine === "abp") && (value.ownership === void 0 || value.ownership === "owned" || value.ownership === "attached") && typeof value.pid === "number" && Number.isFinite(value.pid) && typeof value.startedAt === "number" && Number.isFinite(value.startedAt) && typeof value.updatedAt === "number" && Number.isFinite(value.updatedAt) && typeof value.userDataDir === "string" && value.userDataDir.length > 0;
 }
 function resolveOpensteerStateDir() {
   const explicit = process.env.OPENSTEER_HOME?.trim();
@@ -13804,19 +13897,40 @@ function delay(ms) {
 var OPENSTEER_LOCAL_VIEW_SESSION_LAYOUT = "opensteer-local-view-session";
 var OPENSTEER_LOCAL_VIEW_SESSION_VERSION = 1;
 function buildLocalViewSessionId(input) {
+  const ownership = input.ownership ?? "owned";
+  const identity = ownership === "attached" ? input.endpoint ?? input.remoteDebuggingUrl ?? input.baseUrl ?? "attached" : `pid:${String(input.pid ?? 0)}`;
   const hash = crypto.createHash("sha256").update(`${input.rootPath}
-${String(input.pid)}
+${ownership}
+${identity}
 ${String(input.startedAt)}`).digest("hex");
   return `local_${hash.slice(0, 24)}`;
 }
+function buildLocalViewSessionIdForRecord(input) {
+  const ownership = getPersistedLocalBrowserSessionOwnership(input.live);
+  if (ownership === "attached") {
+    return buildLocalViewSessionId({
+      rootPath: input.rootPath,
+      ownership,
+      startedAt: input.live.startedAt,
+      ...input.live.endpoint === void 0 ? {} : { endpoint: input.live.endpoint },
+      ...input.live.baseUrl === void 0 ? {} : { baseUrl: input.live.baseUrl },
+      ...input.live.remoteDebuggingUrl === void 0 ? {} : { remoteDebuggingUrl: input.live.remoteDebuggingUrl }
+    });
+  }
+  return buildLocalViewSessionId({
+    rootPath: input.rootPath,
+    ownership,
+    startedAt: input.live.startedAt,
+    pid: input.live.pid
+  });
+}
 function createLocalViewSessionManifest(input) {
   return {
     layout: OPENSTEER_LOCAL_VIEW_SESSION_LAYOUT,
     version: OPENSTEER_LOCAL_VIEW_SESSION_VERSION,
-    sessionId: buildLocalViewSessionId({
+    sessionId: buildLocalViewSessionIdForRecord({
       rootPath: input.rootPath,
-      pid: input.live.pid,
-      startedAt: input.live.startedAt
+      live: input.live
     }),
     rootPath: input.rootPath,
     ...input.workspace === void 0 ? {} : { workspace: input.workspace },
@@ -13875,7 +13989,8 @@ function normalizeOpensteerEngineName(value, source = "engine") {
   if (normalized === "playwright" || normalized === "abp") {
     return normalized;
   }
-  throw new Error(
+  throw new OpensteerProtocolError(
+    "invalid-argument",
     `${source} must be one of ${OPENSTEER_ENGINE_NAMES.join(", ")}; received "${value}".`
   );
 }
@@ -13884,7 +13999,8 @@ function assertSupportedEngineOptions(input) {
     return;
   }
   if (typeof input.browser === "object" && input.browser !== null && input.browser.mode === "attach") {
-    throw new Error(
+    throw new OpensteerProtocolError(
+      "invalid-argument",
       'ABP engine does not support browser.mode="attach". Use the Playwright engine for attach flows.'
     );
   }
@@ -13892,7 +14008,8 @@ function assertSupportedEngineOptions(input) {
   if (unsupportedContextOptionNames.length === 0) {
     return;
   }
-  throw new Error(
+  throw new OpensteerProtocolError(
+    "invalid-argument",
     `ABP engine does not support ${unsupportedContextOptionNames.join(", ")}. Supported ABP context options: context.viewport.`
   );
 }
@@ -14014,7 +14131,7 @@ var OpensteerBrowserManager = class {
     }
     const liveRecord = await this.readLivePersistentBrowser(await this.ensureWorkspaceStore());
     return {
-      mode: this.mode,
+      mode: liveRecord?.ownership === "attached" ? "attach" : this.mode,
       engine: liveRecord?.engine ?? this.engineName,
       ...this.workspace === void 0 ? {} : { workspace: this.workspace },
       live: liveRecord !== void 0
@@ -14142,6 +14259,7 @@ var OpensteerBrowserManager = class {
       });
       const liveRecord = {
         mode: "persistent",
+        ownership: "owned",
         engine: "abp",
         baseUrl: launched.baseUrl,
         remoteDebuggingUrl: launched.remoteDebuggingUrl,
@@ -14228,11 +14346,78 @@ var OpensteerBrowserManager = class {
   }
   async createAttachEngine() {
     const endpoint = await resolveAttachEndpoint(this.browserOptions);
-    return this.createAttachedEngine({
-      endpoint,
-      ...this.browserOptions?.headers === void 0 ? {} : { headers: this.browserOptions.headers },
-      freshTab: this.browserOptions?.freshTab ?? true,
-      onDispose: async () => void 0
+    if (this.workspace === void 0) {
+      return this.createAttachedEngine({
+        endpoint,
+        ...this.browserOptions?.headers === void 0 ? {} : { headers: this.browserOptions.headers },
+        freshTab: this.browserOptions?.freshTab ?? true,
+        onDispose: async () => void 0
+      });
+    }
+    const workspace = await this.ensureWorkspaceStore();
+    return workspace.lock(async () => {
+      const live = await this.readLivePersistentBrowser(workspace);
+      if (live) {
+        if (live.engine !== "playwright") {
+          throw new Error(
+            `workspace "${this.workspace}" already has a live ${live.engine} browser. Close it before attaching a Playwright browser.`
+          );
+        }
+        if (live.ownership !== "attached") {
+          throw new Error(
+            `workspace "${this.workspace}" already has a live Opensteer-owned browser. Close it before attaching another browser.`
+          );
+        }
+        if (live.endpoint === void 0) {
+          throw new Error("workspace live browser record is missing a DevTools endpoint.");
+        }
+        if (live.endpoint !== endpoint) {
+          throw new Error(
+            `workspace "${this.workspace}" is already attached to a different browser endpoint. Close it before reattaching.`
+          );
+        }
+        await bestEffortRegisterLocalViewSession({
+          rootPath: workspace.rootPath,
+          ...this.workspace === void 0 ? {} : { workspace: this.workspace },
+          live: toPersistedLocalBrowserSessionRecord(this.workspace, live),
+          ownership: "attached"
+        });
+        return this.createAttachedEngine({
+          endpoint: live.endpoint,
+          ...this.browserOptions?.headers === void 0 ? {} : { headers: this.browserOptions.headers },
+          freshTab: this.browserOptions?.freshTab ?? true,
+          onDispose: async () => void 0
+        });
+      }
+      const liveRecord = {
+        mode: "persistent",
+        ownership: "attached",
+        engine: "playwright",
+        endpoint,
+        pid: 0,
+        startedAt: Date.now(),
+        userDataDir: workspace.browserUserDataDir
+      };
+      await this.writeLivePersistentBrowser(workspace, liveRecord);
+      const persistedLiveRecord = toPersistedLocalBrowserSessionRecord(this.workspace, liveRecord);
+      await bestEffortRegisterLocalViewSession({
+        rootPath: workspace.rootPath,
+        ...this.workspace === void 0 ? {} : { workspace: this.workspace },
+        live: persistedLiveRecord,
+        ownership: "attached"
+      });
+      try {
+        return await this.createAttachedEngine({
+          endpoint,
+          ...this.browserOptions?.headers === void 0 ? {} : { headers: this.browserOptions.headers },
+          freshTab: this.browserOptions?.freshTab ?? true,
+          onDispose: async () => void 0
+        });
+      } catch (error) {
+        await this.unregisterLocalViewSessionForRecord(workspace.rootPath, persistedLiveRecord);
+        await clearPersistedSessionRecord(workspace.rootPath, "local").catch(() => void 0);
+        throw error;
+      }
     });
   }
   async createPersistentEngine() {
@@ -14252,7 +14437,7 @@ var OpensteerBrowserManager = class {
           rootPath: workspace.rootPath,
           ...this.workspace === void 0 ? {} : { workspace: this.workspace },
           live: toPersistedLocalBrowserSessionRecord(this.workspace, live),
-          ownership: "owned"
+          ownership: live.ownership
         });
         return this.createAttachedEngine({
           endpoint: live.endpoint,
@@ -14268,6 +14453,7 @@ var OpensteerBrowserManager = class {
       });
       const liveRecord = {
         mode: "persistent",
+        ownership: "owned",
         engine: "playwright",
         endpoint: launched.endpoint,
         pid: launched.pid,
@@ -14397,7 +14583,20 @@ var OpensteerBrowserManager = class {
     if (live === void 0) {
       return void 0;
     }
-    if (!isProcessRunning(live.pid)) {
+    if (live.ownership === "attached") {
+      const attachedRecord = toPersistedLocalBrowserSessionRecord(this.workspace, live);
+      if (!await isAttachedLocalBrowserSessionReachable(attachedRecord)) {
+        await this.unregisterLocalViewSessionForRecord(workspace.rootPath, attachedRecord);
+        await clearPersistedSessionRecord(workspace.rootPath, "local").catch(() => void 0);
+        return void 0;
+      }
+      return live;
+    }
+    if (!isProcessRunning2(live.pid)) {
+      await this.unregisterLocalViewSessionForRecord(
+        workspace.rootPath,
+        toPersistedLocalBrowserSessionRecord(this.workspace, live)
+      );
       await clearPersistedSessionRecord(workspace.rootPath, "local").catch(() => void 0);
       return void 0;
     }
@@ -14445,6 +14644,10 @@ var OpensteerBrowserManager = class {
       workspace.rootPath,
       toPersistedLocalBrowserSessionRecord(this.workspace, live)
     );
+    if (live.ownership === "attached") {
+      await clearPersistedSessionRecord(workspace.rootPath, "local").catch(() => void 0);
+      return;
+    }
     if (live.engine === "playwright") {
       if (live.endpoint !== void 0) {
         await requestBrowserClose(live.endpoint).catch(() => void 0);
@@ -14473,10 +14676,18 @@ var OpensteerBrowserManager = class {
   }
   async unregisterLocalViewSessionForRecord(rootPath, record) {
     await bestEffortUnregisterLocalViewSession(
-      buildLocalViewSessionId({
+      getPersistedLocalBrowserSessionOwnership(record) === "attached" ? buildLocalViewSessionId({
+        rootPath,
+        startedAt: record.startedAt,
+        ownership: "attached",
+        ...record.endpoint === void 0 ? {} : { endpoint: record.endpoint },
+        ...record.baseUrl === void 0 ? {} : { baseUrl: record.baseUrl },
+        ...record.remoteDebuggingUrl === void 0 ? {} : { remoteDebuggingUrl: record.remoteDebuggingUrl }
+      }) : buildLocalViewSessionId({
         rootPath,
-        pid: record.pid,
-        startedAt: record.startedAt
+        startedAt: record.startedAt,
+        ownership: "owned",
+        pid: record.pid
       })
     );
   }
@@ -14511,6 +14722,7 @@ function toPersistedLocalBrowserSessionRecord(workspace, live) {
     version: 1,
     provider: "local",
     ...workspace === void 0 ? {} : { workspace },
+    ownership: live.ownership,
     engine: live.engine,
     ...live.endpoint === void 0 ? {} : { endpoint: live.endpoint },
     ...live.baseUrl === void 0 ? {} : { baseUrl: live.baseUrl },
@@ -14526,6 +14738,7 @@ function toPersistedLocalBrowserSessionRecord(workspace, live) {
 function toWorkspaceLiveBrowserRecord(record) {
   return {
     mode: "persistent",
+    ownership: getPersistedLocalBrowserSessionOwnership(record),
     engine: record.engine,
     ...record.endpoint === void 0 ? {} : { endpoint: record.endpoint },
     ...record.baseUrl === void 0 ? {} : { baseUrl: record.baseUrl },
@@ -14552,7 +14765,12 @@ function isAttachBrowserOptions(browser) {
 async function resolveAttachEndpoint(browser) {
   const endpoint = browser?.endpoint?.trim();
   if (endpoint && endpoint.length > 0) {
-    return endpoint;
+    const inspected = await inspectCdpEndpoint({
+      endpoint,
+      ...browser?.headers === void 0 ? {} : { headers: browser.headers },
+      timeoutMs: DEFAULT_TIMEOUT_MS
+    });
+    return inspected.endpoint;
   }
   const selection = await selectAttachBrowserCandidate({
     timeoutMs: DEFAULT_TIMEOUT_MS
@@ -14816,12 +15034,12 @@ async function waitForProcessExit(pid, timeoutMs) {
   }
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
-    if (!isProcessRunning(pid)) {
+    if (!isProcessRunning2(pid)) {
       return true;
     }
     await sleep2(50);
   }
-  return !isProcessRunning(pid);
+  return !isProcessRunning2(pid);
 }
 function resolveAbpSessionDir(workspace) {
   return path10__default.default.join(workspace.livePath, "abp-session");
@@ -14994,15 +15212,58 @@ function isOpensteerEnvironmentKey(key) {
   return key.startsWith(OPENSTEER_ENV_PREFIX);
 }
 
-// src/provider/config.ts
-var OPENSTEER_PROVIDER_MODES = ["local", "cloud"];
-function assertProviderSupportsEngine(provider, engine) {
-  if (engine !== "abp") {
-    return;
+// src/internal/errors.ts
+function normalizeThrownOpensteerError(error, fallbackMessage) {
+  if (isOpensteerProtocolError(error)) {
+    return toOpensteerError(error);
   }
-  if (provider === "cloud") {
-    throw new Error(
-      "ABP is not supported for provider=cloud. Cloud provider currently requires Playwright."
+  if (isBrowserCoreError(error)) {
+    return createOpensteerError(error.code, error.message, {
+      retriable: error.retriable,
+      ...error.details === void 0 ? {} : { details: error.details }
+    });
+  }
+  if (error instanceof OpensteerAttachAmbiguousError) {
+    return createOpensteerError("conflict", error.message, {
+      details: {
+        candidates: error.candidates,
+        code: error.code,
+        name: error.name
+      }
+    });
+  }
+  if (error instanceof Error && "opensteerError" in error && typeof error.opensteerError === "object" && error.opensteerError !== null) {
+    const oe = error.opensteerError;
+    return createOpensteerError(oe.code, oe.message, {
+      retriable: oe.retriable,
+      ...oe.capability === void 0 ? {} : { capability: oe.capability },
+      ...oe.details === void 0 ? {} : { details: oe.details }
+    });
+  }
+  if (error instanceof Error) {
+    return createOpensteerError("operation-failed", error.message, {
+      details: {
+        name: error.name
+      }
+    });
+  }
+  return createOpensteerError("internal", fallbackMessage, {
+    details: {
+      value: error
+    }
+  });
+}
+
+// src/provider/config.ts
+var OPENSTEER_PROVIDER_MODES = ["local", "cloud"];
+function assertProviderSupportsEngine(provider, engine) {
+  if (engine !== "abp") {
+    return;
+  }
+  if (provider === "cloud") {
+    throw new OpensteerProtocolError(
+      "invalid-argument",
+      "ABP is not supported for provider=cloud. Cloud provider currently requires Playwright."
     );
   }
 }
@@ -15011,7 +15272,8 @@ function normalizeOpensteerProviderMode(value, source = "OPENSTEER_PROVIDER") {
   if (normalized === OPENSTEER_PROVIDER_MODES[0] || normalized === OPENSTEER_PROVIDER_MODES[1]) {
     return normalized;
   }
-  throw new Error(
+  throw new OpensteerProtocolError(
+    "invalid-argument",
     `${source} must be one of ${OPENSTEER_PROVIDER_MODES.join(", ")}; received "${value}".`
   );
 }
@@ -15451,6 +15713,24 @@ async function sleep3(ms) {
 // src/cloud/client.ts
 var CLOUD_CLOSE_TIMEOUT_MS = 6e4;
 var CLOUD_CLOSE_POLL_INTERVAL_MS = 250;
+var OpensteerCloudRequestError = class extends Error {
+  statusCode;
+  code;
+  details;
+  method;
+  pathname;
+  url;
+  constructor(args) {
+    super(args.message);
+    this.name = "OpensteerCloudRequestError";
+    this.statusCode = args.statusCode;
+    this.code = args.code;
+    this.details = args.details;
+    this.method = args.method;
+    this.pathname = args.pathname;
+    this.url = args.url;
+  }
+};
 var OpensteerCloudClient = class {
   constructor(config) {
     this.config = config;
@@ -15626,7 +15906,11 @@ var OpensteerCloudClient = class {
       });
     }
     if (!response.ok) {
-      throw new Error(`${init.method} ${pathname} failed with ${String(response.status)}.`);
+      throw await createCloudRequestError(response, {
+        method: init.method,
+        pathname,
+        url
+      });
     }
     return response;
   }
@@ -15674,6 +15958,36 @@ function wrapCloudFetchError(error, input) {
   wrapped.name = error.name;
   return wrapped;
 }
+async function createCloudRequestError(response, input) {
+  const payload = await readCloudErrorPayload(response);
+  return new OpensteerCloudRequestError({
+    statusCode: response.status,
+    method: input.method,
+    pathname: input.pathname,
+    url: input.url,
+    message: payload?.error ?? `${input.method} ${input.pathname} failed with ${String(response.status)}.`,
+    ...payload?.code === void 0 ? {} : { code: payload.code },
+    ...payload?.details === void 0 ? {} : { details: payload.details }
+  });
+}
+async function readCloudErrorPayload(response) {
+  try {
+    return asCloudErrorPayload(await response.json());
+  } catch {
+    return void 0;
+  }
+}
+function asCloudErrorPayload(value) {
+  if (value === null || typeof value !== "object") {
+    return void 0;
+  }
+  const payload = value;
+  return {
+    ...typeof payload.error === "string" ? { error: payload.error } : {},
+    ...typeof payload.code === "string" ? { code: payload.code } : {},
+    ..."details" in payload ? { details: payload.details } : {}
+  };
+}
 
 // src/cloud/config.ts
 function resolveCloudConfig(input = {}) {
@@ -15704,13 +16018,13 @@ function resolveCloudConfig(input = {}) {
 
 // ../runtime-core/package.json
 var package_default = {
-  version: "0.2.4"};
+  version: "0.2.6"};
 
 // ../runtime-core/src/version.ts
 var OPENSTEER_RUNTIME_CORE_VERSION = package_default.version;
 
 // ../runtime-core/src/internal/errors.ts
-function normalizeThrownOpensteerError(error, fallbackMessage) {
+function normalizeThrownOpensteerError2(error, fallbackMessage) {
   if (isOpensteerProtocolError(error)) {
     return toOpensteerError(error);
   }
@@ -15975,12 +16289,16 @@ function toOpensteerResolvedTarget(target) {
     documentRef: target.documentRef,
     documentEpoch: target.documentEpoch,
     nodeRef: target.nodeRef,
-    tagName: target.node.nodeName.toUpperCase(),
+    tagName: toOpensteerTagName(target.node.nodeName),
     pathHint: buildPathSelectorHint(target.replayPath ?? target.anchor),
     ...target.persist === void 0 ? {} : { persist: target.persist },
     ...target.selectorUsed === void 0 ? {} : { selectorUsed: target.selectorUsed }
   };
 }
+function toOpensteerTagName(nodeName) {
+  const tagName = String(nodeName).trim().toLowerCase();
+  return tagName.length === 0 ? "element" : tagName;
+}
 
 // ../runtime-core/src/runtimes/computer-use/runtime.ts
 function createComputerUseRuntime(options) {
@@ -16014,7 +16332,7 @@ var DefaultComputerUseRuntime = class {
         screenshot,
         signal: input.timeout.signal,
         remainingMs: () => input.timeout.remainingMs(),
-        policySettle: async (pageRef, trigger) => {
+        policySettle: async (pageRef, trigger, boundary) => {
           try {
             await settleWithPolicy(this.options.policy.settle, {
               operation: "computer.execute",
@@ -16022,7 +16340,9 @@ var DefaultComputerUseRuntime = class {
               engine: this.options.engine,
               pageRef,
               signal: input.timeout.signal,
-              remainingMs: input.timeout.remainingMs()
+              remainingMs: input.timeout.remainingMs(),
+              ...boundary?.observedMutationQuietMs === void 0 ? {} : { observedMutationQuietMs: boundary.observedMutationQuietMs },
+              ...boundary?.postLoadHandled === true ? { postLoadHandled: true } : {}
             });
           } catch (error) {
             if (pageRef === input.pageRef && isSoftSettleTimeoutError(error, input.timeout.signal)) {
@@ -17200,28 +17520,24 @@ function restoreBoundedAttr(el, attr, value) {
   }
   setBoundedAttr(el, attr, value);
 }
-function deduplicateImages(html) {
+function deduplicateImagesInDom($) {
   const seen = /* @__PURE__ */ new Set();
-  return html.replace(/<img\b([^>]*)>/gi, (full, attrContent) => {
-    if (/\bc\s*=/.test(attrContent)) {
-      return full;
-    }
-    const srcMatch = attrContent.match(/\bsrc\s*=\s*(["']?)(.*?)\1/);
-    const srcsetMatch = attrContent.match(/\bsrcset\s*=\s*(["'])(.*?)\1/);
-    let src = null;
-    if (srcMatch && srcMatch[2]) {
-      src = srcMatch[2].trim();
-    } else if (srcsetMatch && srcsetMatch[2]) {
-      src = srcsetMatch[2].split(",")[0]?.trim().split(" ")[0] ?? null;
+  $("img").each(function deduplicateDomImage() {
+    const el = $(this);
+    if (el.attr("c") !== void 0) {
+      return;
     }
+    const srcValue = el.attr("src")?.trim();
+    const srcsetValue = el.attr("srcset");
+    const src = srcValue && srcValue.length > 0 ? srcValue : srcsetValue?.split(",")[0]?.trim().split(/\s+/u)[0];
     if (!src) {
-      return full;
+      return;
     }
     if (seen.has(src)) {
-      return "";
+      el.remove();
+      return;
     }
     seen.add(src);
-    return full;
   });
 }
 function hasAttribute2(node, attr) {
@@ -17279,23 +17595,6 @@ function isPreservedImageElement(node) {
 function getElementsInReverseDocumentOrder($) {
   return $.root().find("*").toArray().reverse().filter((node) => node.type === "tag");
 }
-function getNodeDepth(node) {
-  let depth = 0;
-  let current = node.parent;
-  while (current) {
-    depth++;
-    current = current.parent;
-  }
-  return depth;
-}
-function getElementsByDepthDescending($) {
-  const elements = $.root().find("*").toArray().filter((node) => node.type === "tag");
-  const depths = /* @__PURE__ */ new Map();
-  for (const el of elements) {
-    depths.set(el, getNodeDepth(el));
-  }
-  return elements.sort((a, b) => (depths.get(b) ?? 0) - (depths.get(a) ?? 0));
-}
 function flattenExtractionTree($) {
   for (const node of getElementsInReverseDocumentOrder($)) {
     const el = $(node);
@@ -17313,19 +17612,6 @@ function flattenExtractionTree($) {
     el.replaceWith(el.contents());
   }
 }
-function hasMarkedAncestor(el, attr) {
-  let current = el[0]?.parent;
-  while (current) {
-    if (!isElementLikeNode(current)) {
-      return false;
-    }
-    if (current.attribs?.[attr] !== void 0) {
-      return true;
-    }
-    current = current.parent;
-  }
-  return false;
-}
 function isIndicatorImage(node) {
   return (node?.tagName || "").toLowerCase() === "img" && (hasAttribute2(node, "alt") || hasAttribute2(node, "src") || hasAttribute2(node, "srcset"));
 }
@@ -17443,7 +17729,7 @@ function serializeForExtraction($, root) {
   traverse(root, 0);
   return lines.map((l) => l.trim()).filter((l) => l.length > 0).join("");
 }
-function isClickable($, el, context) {
+function isClickable(el, context) {
   if (context.hasPreMarked) {
     return el.attr(OPENSTEER_INTERACTIVE_ATTR) !== void 0;
   }
@@ -17477,21 +17763,17 @@ function isClickable($, el, context) {
   }
   return false;
 }
-function cleanForExtraction(html) {
+function prepareExtractionSnapshotDom(html) {
   if (!html.trim()) {
-    return "";
+    return void 0;
   }
   const $ = cheerio__namespace.load(html, { xmlMode: false });
   removeNoise($);
   removeComments($);
   markInlineSelfHiddenFallback($);
   pruneSelfHiddenNodes($);
-  const $clean = cheerio__namespace.load(
-    $.html().replace(/\n{2,}/g, "\n").trim(),
-    { xmlMode: false }
-  );
-  $clean("*").each(function stripAndRestoreExtractionAttrs() {
-    const el = $clean(this);
+  $("*").each(function stripAndRestoreExtractionAttrs() {
+    const el = $(this);
     const node = el[0];
     if (!node) {
       return;
@@ -17532,16 +17814,20 @@ function cleanForExtraction(html) {
       restoreBoundedAttr(el, "href", hrefValue);
     }
   });
-  flattenExtractionTree($clean);
-  const root = $clean.root()[0];
+  flattenExtractionTree($);
+  deduplicateImagesInDom($);
+  return $;
+}
+function serializePreparedExtractionSnapshot($) {
+  const root = $.root()[0];
   if (root === void 0) {
     return "";
   }
-  return deduplicateImages(serializeForExtraction($clean, root));
+  return serializeForExtraction($, root);
 }
-function cleanForAction(html) {
+function prepareActionSnapshotDom(html) {
   if (!html.trim()) {
-    return "";
+    return void 0;
   }
   const $ = cheerio__namespace.load(html, { xmlMode: false });
   removeNoise($);
@@ -17550,13 +17836,12 @@ function cleanForAction(html) {
   pruneSelfHiddenNodes($);
   const clickableMark = "data-clickable-marker";
   const indicatorMark = "data-keep-indicator";
-  const branchMark = "data-keep-branch";
   const context = {
     hasPreMarked: $(`[${OPENSTEER_INTERACTIVE_ATTR}]`).length > 0
   };
   $("*").each(function markClickables() {
     const el = $(this);
-    if (isClickable($, el, context)) {
+    if (isClickable(el, context)) {
       el.attr(clickableMark, "1");
     }
   });
@@ -17586,25 +17871,7 @@ function cleanForAction(html) {
       el.remove();
     }
   });
-  $(`[${clickableMark}], [${indicatorMark}]`).each(function markBranches() {
-    let current = $(this).parent();
-    while (current.length > 0) {
-      const node = current[0];
-      if (!node || node.type !== "tag") {
-        break;
-      }
-      const ancestor = current;
-      const tag = (node.tagName || "").toLowerCase();
-      if (ROOT_TAGS.has(tag) || ancestor.attr(clickableMark) !== void 0) {
-        break;
-      }
-      if (!isBoundaryTag(tag)) {
-        ancestor.attr(branchMark, "1");
-      }
-      current = ancestor.parent();
-    }
-  });
-  for (const node of getElementsByDepthDescending($)) {
+  for (const node of getElementsInReverseDocumentOrder($)) {
     const el = $(node);
     const tag = (node.tagName || "").toLowerCase();
     if (ROOT_TAGS.has(tag) || isBoundaryTag(tag)) {
@@ -17613,17 +17880,7 @@ function cleanForAction(html) {
     if (el.attr(clickableMark) !== void 0 || el.attr(indicatorMark) !== void 0) {
       continue;
     }
-    const insideClickable = hasMarkedAncestor(el, clickableMark);
-    const preserveBranch = el.attr(branchMark) !== void 0;
     const hasContent = hasElementChildren(node) || hasDirectText(node);
-    if (insideClickable || preserveBranch) {
-      if (!hasContent) {
-        el.remove();
-      } else {
-        unwrapActionNode($, el);
-      }
-      continue;
-    }
     if (!hasContent) {
       el.remove();
       continue;
@@ -17724,13 +17981,20 @@ function cleanForAction(html) {
     }
     el.removeAttr(clickableMark);
     el.removeAttr(indicatorMark);
-    el.removeAttr(branchMark);
     el.removeAttr(OPENSTEER_INTERACTIVE_ATTR);
     el.removeAttr(OPENSTEER_HIDDEN_ATTR);
     el.removeAttr(OPENSTEER_SCROLLABLE_ATTR);
     el.removeAttr(OPENSTEER_SELF_HIDDEN_ATTR);
   });
-  return compactHtml(deduplicateImages($.html()));
+  deduplicateImagesInDom($);
+  return $;
+}
+function serializePreparedActionSnapshot($) {
+  const normalized = compactHtml($.html());
+  if (normalized.length === 0) {
+    return "";
+  }
+  return cheerio__namespace.load(normalized, { xmlMode: false }).html();
 }
 var VOID_TAGS2 = /* @__PURE__ */ new Set([
   "area",
@@ -17953,27 +18217,32 @@ async function markLiveSnapshotSemantics(options) {
   const frames = await options.engine.listFrames({
     pageRef: options.pageRef
   });
-  for (const frame of frames) {
-    await evaluateFrameBestEffort(
-      options.engine,
-      frame.frameRef,
-      MARK_SNAPSHOT_SEMANTICS_SCRIPT,
-      SNAPSHOT_SEMANTIC_ARGS
-    );
-  }
-  return async () => {
-    for (const frame of frames) {
-      await evaluateFrameBestEffort(
+  await Promise.all(
+    frames.map(
+      (frame) => evaluateFrameBestEffort(
         options.engine,
         frame.frameRef,
-        CLEAR_SNAPSHOT_SEMANTICS_SCRIPT,
-        CLEAR_SNAPSHOT_SEMANTIC_ARGS
-      );
-    }
+        MARK_SNAPSHOT_SEMANTICS_SCRIPT,
+        SNAPSHOT_SEMANTIC_ARGS
+      )
+    )
+  );
+  return async () => {
+    await Promise.all(
+      frames.map(
+        (frame) => evaluateFrameBestEffort(
+          options.engine,
+          frame.frameRef,
+          CLEAR_SNAPSHOT_SEMANTICS_SCRIPT,
+          CLEAR_SNAPSHOT_SEMANTIC_ARGS
+        )
+      )
+    );
   };
 }
 
 // ../runtime-core/src/sdk/snapshot/compiler.ts
+var EXTRACTION_SKIPPED_COUNTER_TAGS = /* @__PURE__ */ new Set(["html", "head", "body"]);
 var INTERNAL_SNAPSHOT_ATTRIBUTE_NAMES = /* @__PURE__ */ new Set([
   "c",
   OPENSTEER_BOUNDARY_ATTR,
@@ -17988,7 +18257,7 @@ var INTERNAL_SNAPSHOT_ATTRIBUTE_NAMES = /* @__PURE__ */ new Set([
 var MAX_LIVE_COUNTER_SYNC_ATTEMPTS = 4;
 var CLEAR_LIVE_COUNTERS_SCRIPT = `(({ sparseCounterAttr }) => {
   const walk = (root) => {
-    for (const child of root.children) {
+    for (const child of Array.from(root?.children || [])) {
       child.removeAttribute("c");
       child.removeAttribute(sparseCounterAttr);
       walk(child);
@@ -18004,7 +18273,7 @@ var CLEAR_LIVE_COUNTERS_SCRIPT = `(({ sparseCounterAttr }) => {
 var ASSIGN_SPARSE_COUNTERS_SCRIPT = `(({ sparseCounterAttr, startCounter }) => {
   let counter = startCounter;
   const walk = (root) => {
-    for (const child of root.children) {
+    for (const child of Array.from(root?.children || [])) {
       child.setAttribute(sparseCounterAttr, String(counter++));
       walk(child);
       if (child.shadowRoot) {
@@ -18018,7 +18287,7 @@ var ASSIGN_SPARSE_COUNTERS_SCRIPT = `(({ sparseCounterAttr, startCounter }) => {
 })`;
 var APPLY_DENSE_COUNTERS_SCRIPT = `(({ sparseCounterAttr, mapping }) => {
   const walk = (root) => {
-    for (const child of root.children) {
+    for (const child of Array.from(root?.children || [])) {
       child.removeAttribute("c");
       const sparse = child.getAttribute(sparseCounterAttr);
       if (sparse !== null) {
@@ -18081,20 +18350,22 @@ function ensureSparseCountersForAllRecords(counterRecords) {
 async function clearOpensteerLiveCounters(engine, pageRef) {
   const frames = await engine.listFrames({ pageRef });
   const failures = [];
-  for (const frame of frames) {
-    try {
-      await engine.evaluateFrame({
-        frameRef: frame.frameRef,
-        script: CLEAR_LIVE_COUNTERS_SCRIPT,
-        args: [{ sparseCounterAttr: OPENSTEER_SPARSE_COUNTER_ATTR }]
-      });
-    } catch (error) {
-      if (isDetachedFrameSyncError(error)) {
-        continue;
+  await Promise.all(
+    frames.map(async (frame) => {
+      try {
+        await engine.evaluateFrame({
+          frameRef: frame.frameRef,
+          script: CLEAR_LIVE_COUNTERS_SCRIPT,
+          args: [{ sparseCounterAttr: OPENSTEER_SPARSE_COUNTER_ATTR }]
+        });
+      } catch (error) {
+        if (isDetachedFrameSyncError(error)) {
+          return;
+        }
+        failures.push(`frame ${frame.frameRef} could not be cleared (${describeError(error)}).`);
       }
-      failures.push(`frame ${frame.frameRef} could not be cleared (${describeError(error)}).`);
-    }
-  }
+    })
+  );
   if (failures.length > 0) {
     throw buildLiveCounterSyncError("clear live counters", failures);
   }
@@ -18143,25 +18414,29 @@ async function syncDenseCountersToLiveDom(engine, pageRef, sparseToDirectMapping
       denseCounter
     ])
   );
-  for (const frame of frames) {
-    try {
-      await engine.evaluateFrame({
-        frameRef: frame.frameRef,
-        script: APPLY_DENSE_COUNTERS_SCRIPT,
-        args: [
-          {
-            sparseCounterAttr: OPENSTEER_SPARSE_COUNTER_ATTR,
-            mapping: mappingObj
-          }
-        ]
-      });
-    } catch (error) {
-      if (isDetachedFrameSyncError(error)) {
-        continue;
+  await Promise.all(
+    frames.map(async (frame) => {
+      try {
+        await engine.evaluateFrame({
+          frameRef: frame.frameRef,
+          script: APPLY_DENSE_COUNTERS_SCRIPT,
+          args: [
+            {
+              sparseCounterAttr: OPENSTEER_SPARSE_COUNTER_ATTR,
+              mapping: mappingObj
+            }
+          ]
+        });
+      } catch (error) {
+        if (isDetachedFrameSyncError(error)) {
+          return;
+        }
+        failures.push(
+          `frame ${frame.frameRef} could not be synchronized (${describeError(error)}).`
+        );
       }
-      failures.push(`frame ${frame.frameRef} could not be synchronized (${describeError(error)}).`);
-    }
-  }
+    })
+  );
   if (failures.length > 0) {
     throw buildLiveCounterSyncError("synchronize dense counters", failures);
   }
@@ -18179,26 +18454,26 @@ async function compileOpensteerSnapshot(options) {
       await clearOpensteerLiveCounters(options.engine, options.pageRef);
       await assignSparseCountersToLiveDom(options.engine, options.pageRef);
       const pageInfo = await options.engine.getPageInfo({ pageRef: options.pageRef });
-      const mainSnapshot = await getMainDocumentSnapshot(options.engine, options.pageRef);
-      const snapshotsByDocumentRef = await collectDocumentSnapshots(options.engine, mainSnapshot);
+      const { mainSnapshot, snapshotsByDocumentRef } = await getPageDocumentSnapshots(
+        options.engine,
+        options.pageRef
+      );
       await cleanupLiveSemantics();
       cleanupLiveSemantics = async () => {
       };
-      const snapshotIndices = /* @__PURE__ */ new Map();
       const renderedNodes = /* @__PURE__ */ new Map();
       const rawHtml = renderDocumentSnapshot(
         mainSnapshot.documentRef,
         snapshotsByDocumentRef,
-        snapshotIndices,
         renderedNodes,
         {
           iframeDepth: 0,
           shadowDepth: 0
         }
       );
-      const cleanedHtml = options.mode === "extraction" ? cleanForExtraction(rawHtml) : cleanForAction(rawHtml);
-      const compiledHtml = assignCounters(cleanedHtml, renderedNodes);
-      const finalHtml = options.mode === "extraction" ? unwrapExtractionHtml(compiledHtml.html) : compiledHtml.html;
+      const preparedSnapshotDom = options.mode === "extraction" ? prepareExtractionSnapshotDom(rawHtml) : prepareActionSnapshotDom(rawHtml);
+      const compiledHtml = assignCountersInDom(preparedSnapshotDom, renderedNodes, options.mode);
+      const finalHtml = preparedSnapshotDom === void 0 ? "" : options.mode === "extraction" ? serializePreparedExtractionSnapshot(preparedSnapshotDom) : serializePreparedActionSnapshot(preparedSnapshotDom);
       ensureSparseCountersForAllRecords(compiledHtml.counterRecords);
       await syncDenseCountersToLiveDom(
         options.engine,
@@ -18233,6 +18508,25 @@ async function getMainDocumentSnapshot(engine, pageRef) {
   }
   return engine.getDomSnapshot({ frameRef: mainFrame.frameRef });
 }
+async function getPageDocumentSnapshots(engine, pageRef) {
+  const bundleEngine = engine;
+  const bundledSnapshots = await bundleEngine.getPageDomSnapshots?.({ pageRef });
+  if (bundledSnapshots && bundledSnapshots.length > 0) {
+    const mainSnapshot2 = bundledSnapshots.find((snapshot) => snapshot.parentDocumentRef === void 0) ?? bundledSnapshots[0];
+    return {
+      mainSnapshot: mainSnapshot2,
+      snapshotsByDocumentRef: new Map(
+        bundledSnapshots.map((snapshot) => [snapshot.documentRef, snapshot])
+      )
+    };
+  }
+  const mainSnapshot = await getMainDocumentSnapshot(engine, pageRef);
+  const snapshotsByDocumentRef = await collectDocumentSnapshots(engine, mainSnapshot);
+  return {
+    mainSnapshot,
+    snapshotsByDocumentRef
+  };
+}
 async function collectDocumentSnapshots(engine, mainSnapshot) {
   const snapshotsByDocumentRef = /* @__PURE__ */ new Map([
     [mainSnapshot.documentRef, mainSnapshot]
@@ -18251,7 +18545,7 @@ async function collectDocumentSnapshots(engine, mainSnapshot) {
   }
   return snapshotsByDocumentRef;
 }
-function renderDocumentSnapshot(documentRef, snapshotsByDocumentRef, snapshotIndices, renderedNodes, depth) {
+function renderDocumentSnapshot(documentRef, snapshotsByDocumentRef, renderedNodes, depth) {
   const snapshot = snapshotsByDocumentRef.get(documentRef);
   if (!snapshot) {
     return "";
@@ -18263,17 +18557,9 @@ function renderDocumentSnapshot(documentRef, snapshotsByDocumentRef, snapshotInd
       `snapshot ${snapshot.documentRef} is missing root node ${String(snapshot.rootSnapshotNodeId)}`
     );
   }
-  return renderNode(
-    snapshot,
-    rootNode,
-    nodesById,
-    snapshotsByDocumentRef,
-    snapshotIndices,
-    renderedNodes,
-    depth
-  );
+  return renderNode(snapshot, rootNode, nodesById, snapshotsByDocumentRef, renderedNodes, depth);
 }
-function renderNode(snapshot, node, nodesById, snapshotsByDocumentRef, snapshotIndices, renderedNodes, depth) {
+function renderNode(snapshot, node, nodesById, snapshotsByDocumentRef, renderedNodes, depth) {
   if (node.nodeType === 3) {
     return escapeHtml(node.nodeValue || node.textContent || "");
   }
@@ -18281,56 +18567,26 @@ function renderNode(snapshot, node, nodesById, snapshotsByDocumentRef, snapshotI
     return "";
   }
   if (node.nodeType === 9 || node.nodeType === 11) {
-    return renderChildren(
-      snapshot,
-      node,
-      nodesById,
-      snapshotsByDocumentRef,
-      snapshotIndices,
-      renderedNodes,
-      depth
-    );
+    return renderChildren(snapshot, node, nodesById, snapshotsByDocumentRef, renderedNodes, depth);
   }
   if (node.nodeType !== 1) {
-    return renderChildren(
-      snapshot,
-      node,
-      nodesById,
-      snapshotsByDocumentRef,
-      snapshotIndices,
-      renderedNodes,
-      depth
-    );
+    return renderChildren(snapshot, node, nodesById, snapshotsByDocumentRef, renderedNodes, depth);
   }
   const tagName = normalizeTagName(node.nodeName);
   if (isPseudoElementTagName(tagName)) {
-    return renderChildren(
-      snapshot,
-      node,
-      nodesById,
-      snapshotsByDocumentRef,
-      snapshotIndices,
-      renderedNodes,
-      depth
-    );
+    return renderChildren(snapshot, node, nodesById, snapshotsByDocumentRef, renderedNodes, depth);
   }
   if ((depth.iframeDepth > 0 || depth.shadowDepth > 0) && (tagName === "html" || tagName === "head" || tagName === "body")) {
-    return renderChildren(
-      snapshot,
-      node,
-      nodesById,
-      snapshotsByDocumentRef,
-      snapshotIndices,
-      renderedNodes,
-      depth
-    );
+    return renderChildren(snapshot, node, nodesById, snapshotsByDocumentRef, renderedNodes, depth);
   }
   const snapshotAttributes = normalizeNodeAttributes(node.attributes);
+  const snapshotAttributeIndex = indexNodeAttributes(snapshotAttributes);
   const authoredAttributes = stripInternalSnapshotAttributes(snapshotAttributes);
+  const authoredAttributeIndex = indexNodeAttributes(authoredAttributes);
   const attributes = [...authoredAttributes];
-  const subtreeHidden = hasAttribute3(snapshotAttributes, OPENSTEER_HIDDEN_ATTR) || isLikelySubtreeHidden(node);
-  const selfHidden = !subtreeHidden && (hasAttribute3(snapshotAttributes, OPENSTEER_SELF_HIDDEN_ATTR) || isLikelySelfHidden(node, nodesById));
-  const interactive = !subtreeHidden && !selfHidden && (hasAttribute3(snapshotAttributes, OPENSTEER_INTERACTIVE_ATTR) || isLikelyInteractive(tagName, node, authoredAttributes));
+  const subtreeHidden = snapshotAttributeIndex.has(OPENSTEER_HIDDEN_ATTR) || isLikelySubtreeHidden(node);
+  const selfHidden = !subtreeHidden && (snapshotAttributeIndex.has(OPENSTEER_SELF_HIDDEN_ATTR) || isLikelySelfHidden(node, nodesById));
+  const interactive = !subtreeHidden && !selfHidden && (snapshotAttributeIndex.has(OPENSTEER_INTERACTIVE_ATTR) || isLikelyInteractive(tagName, node, authoredAttributes, authoredAttributeIndex));
   if (interactive) {
     attributes.push({ name: OPENSTEER_INTERACTIVE_ATTR, value: "1" });
   }
@@ -18339,7 +18595,7 @@ function renderNode(snapshot, node, nodesById, snapshotsByDocumentRef, snapshotI
   } else if (selfHidden) {
     attributes.push({ name: OPENSTEER_SELF_HIDDEN_ATTR, value: "1" });
   }
-  const sparseCounter = findAttributeValue(snapshotAttributes, OPENSTEER_SPARSE_COUNTER_ATTR);
+  const sparseCounter = snapshotAttributeIndex.get(OPENSTEER_SPARSE_COUNTER_ATTR);
   if (sparseCounter !== void 0) {
     attributes.push({ name: OPENSTEER_SPARSE_COUNTER_ATTR, value: sparseCounter });
   }
@@ -18350,21 +18606,18 @@ function renderNode(snapshot, node, nodesById, snapshotsByDocumentRef, snapshotI
     const syntheticNodeId = buildSyntheticNodeId(snapshot, node);
     attributes.push({ name: OPENSTEER_NODE_ID_ATTR, value: syntheticNodeId });
     renderedNodes.set(syntheticNodeId, {
-      locator: createNodeLocator(snapshot.documentRef, snapshot.documentEpoch, node.nodeRef),
-      anchor: buildSnapshotElementAnchor(snapshot, node, snapshotsByDocumentRef, snapshotIndices),
       pageRef: snapshot.pageRef,
       frameRef: snapshot.frameRef,
       documentRef: snapshot.documentRef,
       documentEpoch: snapshot.documentEpoch,
       nodeRef: node.nodeRef,
       tagName: tagName.toUpperCase(),
-      pathHint: buildPathHint(tagName, authoredAttributes),
-      ...buildTextSnippet(node.textContent) === void 0 ? {} : { text: buildTextSnippet(node.textContent) },
       ...authoredAttributes.length === 0 ? {} : { attributes: authoredAttributes },
       iframeDepth: depth.iframeDepth,
       shadowDepth: depth.shadowDepth,
       interactive,
-      liveCounterSyncEligible: isLiveCounterSyncEligible(node, nodesById)
+      liveCounterSyncEligible: isLiveCounterSyncEligible(node, nodesById),
+      ...node.textContent === void 0 ? {} : { textContent: node.textContent }
     });
   }
   const attributeText = attributesToHtml(attributes);
@@ -18373,7 +18626,6 @@ function renderNode(snapshot, node, nodesById, snapshotsByDocumentRef, snapshotI
     node,
     nodesById,
     snapshotsByDocumentRef,
-    snapshotIndices,
     renderedNodes,
     depth
   );
@@ -18384,7 +18636,6 @@ function renderNode(snapshot, node, nodesById, snapshotsByDocumentRef, snapshotI
   const iframeHtml = renderDocumentSnapshot(
     node.contentDocumentRef,
     snapshotsByDocumentRef,
-    snapshotIndices,
     renderedNodes,
     {
       iframeDepth: depth.iframeDepth + 1,
@@ -18396,7 +18647,7 @@ function renderNode(snapshot, node, nodesById, snapshotsByDocumentRef, snapshotI
   }
   return `${elementHtml}<${OPENSTEER_IFRAME_BOUNDARY_TAG} ${OPENSTEER_BOUNDARY_ATTR}="iframe">${iframeHtml}</${OPENSTEER_IFRAME_BOUNDARY_TAG}>`;
 }
-function renderChildren(snapshot, node, nodesById, snapshotsByDocumentRef, snapshotIndices, renderedNodes, depth) {
+function renderChildren(snapshot, node, nodesById, snapshotsByDocumentRef, renderedNodes, depth) {
   const regularChildren = [];
   const shadowChildren = [];
   for (const childSnapshotNodeId of node.childSnapshotNodeIds) {
@@ -18413,18 +18664,10 @@ function renderChildren(snapshot, node, nodesById, snapshotsByDocumentRef, snaps
   const chunks = [];
   if (shadowChildren.length > 0) {
     const shadowHtml = shadowChildren.map(
-      (child) => renderNode(
-        snapshot,
-        child,
-        nodesById,
-        snapshotsByDocumentRef,
-        snapshotIndices,
-        renderedNodes,
-        {
-          iframeDepth: depth.iframeDepth,
-          shadowDepth: depth.shadowDepth + 1
-        }
-      )
+      (child) => renderNode(snapshot, child, nodesById, snapshotsByDocumentRef, renderedNodes, {
+        iframeDepth: depth.iframeDepth,
+        shadowDepth: depth.shadowDepth + 1
+      })
     ).join("");
     chunks.push(
       `<${OPENSTEER_SHADOW_BOUNDARY_TAG} ${OPENSTEER_BOUNDARY_ATTR}="shadow">${shadowHtml}</${OPENSTEER_SHADOW_BOUNDARY_TAG}>`
@@ -18432,24 +18675,21 @@ function renderChildren(snapshot, node, nodesById, snapshotsByDocumentRef, snaps
   }
   for (const child of regularChildren) {
     chunks.push(
-      renderNode(
-        snapshot,
-        child,
-        nodesById,
-        snapshotsByDocumentRef,
-        snapshotIndices,
-        renderedNodes,
-        depth
-      )
+      renderNode(snapshot, child, nodesById, snapshotsByDocumentRef, renderedNodes, depth)
     );
   }
   return chunks.join("");
 }
-function assignCounters(cleanedHtml, renderedNodes) {
-  const $ = cheerio__namespace.load(cleanedHtml, { xmlMode: false });
+function assignCountersInDom($, renderedNodes, mode) {
   const counterRecords = /* @__PURE__ */ new Map();
   const sparseToDirectMapping = /* @__PURE__ */ new Map();
   let nextCounter = 1;
+  if (!$) {
+    return {
+      counterRecords,
+      sparseToDirectMapping
+    };
+  }
   $("*").each(function assignElementCounter() {
     const el = $(this);
     const syntheticNodeId = el.attr(OPENSTEER_NODE_ID_ATTR);
@@ -18461,14 +18701,24 @@ function assignCounters(cleanedHtml, renderedNodes) {
     if (!rendered) {
       return;
     }
+    if (mode === "extraction" && EXTRACTION_SKIPPED_COUNTER_TAGS.has(rendered.tagName.toLowerCase())) {
+      el.removeAttr(OPENSTEER_SPARSE_COUNTER_ATTR);
+      return;
+    }
     const rawSparseCounter = el.attr(OPENSTEER_SPARSE_COUNTER_ATTR);
     el.removeAttr(OPENSTEER_SPARSE_COUNTER_ATTR);
     const sparseCounter = rawSparseCounter ? Number.parseInt(rawSparseCounter, 10) : void 0;
+    const replayableSparseCounter = typeof sparseCounter === "number" && Number.isFinite(sparseCounter) ? sparseCounter : void 0;
+    if (rendered.liveCounterSyncEligible && replayableSparseCounter === void 0) {
+      return;
+    }
     const counter = nextCounter++;
     el.attr("c", String(counter));
-    if (sparseCounter !== void 0 && Number.isFinite(sparseCounter)) {
-      sparseToDirectMapping.set(sparseCounter, counter);
+    if (replayableSparseCounter !== void 0) {
+      sparseToDirectMapping.set(replayableSparseCounter, counter);
     }
+    const pathHint = buildPathHint(rendered.tagName.toLowerCase(), rendered.attributes ?? []);
+    const text = buildTextSnippet(rendered.textContent);
     counterRecords.set(counter, {
       element: counter,
       pageRef: rendered.pageRef,
@@ -18477,20 +18727,17 @@ function assignCounters(cleanedHtml, renderedNodes) {
       documentEpoch: rendered.documentEpoch,
       nodeRef: rendered.nodeRef,
       tagName: rendered.tagName,
-      pathHint: rendered.pathHint,
-      ...rendered.text === void 0 ? {} : { text: rendered.text },
+      pathHint,
+      ...text === void 0 ? {} : { text },
       ...rendered.attributes === void 0 ? {} : { attributes: rendered.attributes },
       iframeDepth: rendered.iframeDepth,
       shadowDepth: rendered.shadowDepth,
       interactive: rendered.interactive,
       liveCounterSyncEligible: rendered.liveCounterSyncEligible,
-      locator: rendered.locator,
-      anchor: rendered.anchor,
-      ...sparseCounter !== void 0 && Number.isFinite(sparseCounter) ? { sparseCounter } : {}
+      ...replayableSparseCounter === void 0 ? {} : { sparseCounter: replayableSparseCounter }
     });
   });
   return {
-    html: $.html(),
     counterRecords,
     sparseToDirectMapping
   };
@@ -18564,28 +18811,28 @@ function isLikelySelfHidden(node, nodesById) {
   }
   return !hasVisibleOutOfFlowChild(node, nodesById);
 }
-function isLikelyInteractive(tagName, node, attributes) {
+function isLikelyInteractive(tagName, node, attributes, attributeIndex) {
   if (NATIVE_INTERACTIVE_TAGS.has(tagName)) {
-    if (tagName === "input" && findAttributeValue(attributes, "type")?.toLowerCase() === "hidden") {
+    if (tagName === "input" && attributeIndex.get("type")?.toLowerCase() === "hidden") {
       return false;
     }
     if (tagName !== "a") {
       return true;
     }
   }
-  if (tagName === "a" && findAttributeValue(attributes, "href") !== void 0) {
+  if (tagName === "a" && attributeIndex.has("href")) {
     return true;
   }
-  if (findAttributeValue(attributes, "onclick") !== void 0 || findAttributeValue(attributes, "onmousedown") !== void 0 || findAttributeValue(attributes, "onmouseup") !== void 0 || findAttributeValue(attributes, "data-action") !== void 0 || findAttributeValue(attributes, "data-click") !== void 0 || findAttributeValue(attributes, "data-toggle") !== void 0) {
+  if (attributeIndex.has("onclick") || attributeIndex.has("onmousedown") || attributeIndex.has("onmouseup") || attributeIndex.has("data-action") || attributeIndex.has("data-click") || attributeIndex.has("data-toggle")) {
     return true;
   }
-  if (hasNonNegativeTabIndex(findAttributeValue(attributes, "tabindex"))) {
+  if (hasNonNegativeTabIndex(attributeIndex.get("tabindex"))) {
     return true;
   }
-  if (findAttributeValue(attributes, "contenteditable")?.toLowerCase() === "true") {
+  if (attributeIndex.get("contenteditable")?.toLowerCase() === "true") {
     return true;
   }
-  const role = findAttributeValue(attributes, "role")?.toLowerCase();
+  const role = attributeIndex.get("role")?.toLowerCase();
   return role !== void 0 && INTERACTIVE_ROLE_SET.has(role);
 }
 function hasVisibleOutOfFlowChild(node, nodesById) {
@@ -18648,14 +18895,6 @@ function parseOpacity(value) {
   const parsed = Number.parseFloat(value);
   return Number.isFinite(parsed) ? parsed : Number.NaN;
 }
-function hasAttribute3(attributes, name) {
-  const normalizedName = name.toLowerCase();
-  return attributes.some((attribute) => attribute.name.toLowerCase() === normalizedName);
-}
-function unwrapExtractionHtml(html) {
-  const $ = cheerio__namespace.load(html, { xmlMode: false });
-  return $("body").html()?.trim() || html;
-}
 function buildSyntheticNodeId(snapshot, node) {
   return `${snapshot.documentRef}:${String(snapshot.documentEpoch)}:${String(node.snapshotNodeId)}`;
 }
@@ -18702,6 +18941,13 @@ function findAttributeValue(attributes, name) {
   const normalizedName = name.toLowerCase();
   return attributes.find((attribute) => attribute.name.toLowerCase() === normalizedName)?.value;
 }
+function indexNodeAttributes(attributes) {
+  const indexed = /* @__PURE__ */ new Map();
+  for (const attribute of attributes) {
+    indexed.set(attribute.name.toLowerCase(), attribute.value);
+  }
+  return indexed;
+}
 function attributesToHtml(attributes) {
   if (attributes.length === 0) {
     return "";
@@ -18711,56 +18957,6 @@ function attributesToHtml(attributes) {
 function escapeAttribute(value) {
   return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
-function buildSnapshotElementAnchor(snapshot, node, snapshotsByDocumentRef, snapshotIndices) {
-  const index = getSnapshotIndex(snapshot.documentRef, snapshotsByDocumentRef, snapshotIndices);
-  const localAnchor = buildLocalStructuralElementAnchor(index, node);
-  return prefixIframeContext(snapshot, localAnchor, snapshotsByDocumentRef, snapshotIndices);
-}
-function prefixIframeContext(snapshot, localPath, snapshotsByDocumentRef, snapshotIndices) {
-  if (snapshot.parentDocumentRef === void 0) {
-    return sanitizeStructuralElementAnchor(localPath);
-  }
-  const parentSnapshot = snapshotsByDocumentRef.get(snapshot.parentDocumentRef);
-  if (!parentSnapshot) {
-    throw new Error(
-      `document ${snapshot.documentRef} has parent ${snapshot.parentDocumentRef} but no parent snapshot`
-    );
-  }
-  const parentIndex = getSnapshotIndex(
-    parentSnapshot.documentRef,
-    snapshotsByDocumentRef,
-    snapshotIndices
-  );
-  const iframeHost = findIframeHostNode(parentIndex, snapshot.documentRef);
-  if (!iframeHost) {
-    throw new Error(
-      `document ${snapshot.documentRef} has parent ${snapshot.parentDocumentRef} but no iframe host`
-    );
-  }
-  const hostPath = buildSnapshotElementAnchor(
-    parentSnapshot,
-    iframeHost,
-    snapshotsByDocumentRef,
-    snapshotIndices
-  );
-  return sanitizeStructuralElementAnchor({
-    context: [...hostPath.context, { kind: "iframe", host: hostPath.nodes }, ...localPath.context],
-    nodes: localPath.nodes
-  });
-}
-function getSnapshotIndex(documentRef, snapshotsByDocumentRef, snapshotIndices) {
-  const existing = snapshotIndices.get(documentRef);
-  if (existing) {
-    return existing;
-  }
-  const snapshot = snapshotsByDocumentRef.get(documentRef);
-  if (!snapshot) {
-    throw new Error(`missing DOM snapshot for ${documentRef}`);
-  }
-  const index = createSnapshotIndex(snapshot);
-  snapshotIndices.set(documentRef, index);
-  return index;
-}
 function escapeHtml(value) {
   return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
@@ -19973,7 +20169,7 @@ var OpensteerSessionRuntime = class {
           options
         );
       }
-      return this.readSessionState();
+      return this.readNavigationSummary();
     }
     const startedAt = Date.now();
     const root = await this.ensureRoot();
@@ -19994,7 +20190,8 @@ var OpensteerSessionRuntime = class {
           openedSessionRef = sessionRef;
           const createdPage = await timeout.runStep(
             () => engine.createPage({
-              sessionRef
+              sessionRef,
+              ...input.url === void 0 ? {} : { url: input.url }
             })
           );
           openedPageRef = createdPage.data.pageRef;
@@ -20004,18 +20201,19 @@ var OpensteerSessionRuntime = class {
           await timeout.runStep(() => this.ensureSemantics());
           let frameRef2 = createdPage.frameRef;
           if (input.url !== void 0) {
-            const navigation = await this.navigatePage(
-              {
+            await timeout.runStep(
+              () => settleWithPolicy(this.policy.settle, {
                 operation: "session.open",
+                trigger: "navigation",
+                engine: this.requireEngine(),
                 pageRef: createdPage.data.pageRef,
-                url: input.url
-              },
-              timeout
+                signal: timeout.signal,
+                remainingMs: timeout.remainingMs()
+              })
             );
-            frameRef2 = navigation.data.mainFrame.frameRef;
           }
           return {
-            state: await timeout.runStep(() => this.readSessionState()),
+            state: await timeout.runStep(() => this.readNavigationSummary()),
             frameRef: frameRef2
           };
         },
@@ -20108,7 +20306,11 @@ var OpensteerSessionRuntime = class {
           "page.new cannot use openerPageRef before a session exists"
         );
       }
-      return this.open(input.url === void 0 ? {} : { url: input.url }, options);
+      const summary = await this.open(input.url === void 0 ? {} : { url: input.url }, options);
+      return {
+        pageRef: await this.ensurePageRef(),
+        ...summary
+      };
     }
     const startedAt = Date.now();
     try {
@@ -20123,7 +20325,7 @@ var OpensteerSessionRuntime = class {
             })
           );
           this.pageRef = created.data.pageRef;
-          return this.readSessionState();
+          return this.readCreatedPageOutput(created.data.pageRef);
         },
         options
       );
@@ -20165,7 +20367,7 @@ var OpensteerSessionRuntime = class {
             () => this.requireEngine().activatePage({ pageRef: input.pageRef })
           );
           this.pageRef = input.pageRef;
-          return this.readSessionState();
+          return this.readNavigationSummary(input.pageRef);
         },
         options
       );
@@ -20291,7 +20493,7 @@ var OpensteerSessionRuntime = class {
           timeout.throwIfAborted();
           return {
             navigation: navigation2,
-            state: await timeout.runStep(() => this.readSessionState())
+            state: await timeout.runStep(() => this.readNavigationSummary(pageRef))
           };
         },
         (diagnostics) => {
@@ -21525,7 +21727,7 @@ var OpensteerSessionRuntime = class {
     let mutationCaptureDiagnostics;
     let boundaryDiagnostics;
     try {
-      const { artifacts, output } = await this.runMutationCapturedOperation(
+      const { artifacts, output, result } = await this.runMutationCapturedOperation(
         "computer.execute",
         {
           ...input.captureNetwork === void 0 ? {} : { captureNetwork: input.captureNetwork },
@@ -21543,9 +21745,14 @@ var OpensteerSessionRuntime = class {
             await this.invalidateLiveSnapshotCounters([pageRef, output2.pageRef], timeout);
             this.pageRef = output2.pageRef;
             const artifacts2 = await this.persistComputerArtifacts(output2, timeout);
+            const result2 = {
+              ...await timeout.runStep(() => this.readNavigationSummary(output2.pageRef)),
+              screenshot: artifacts2.screenshot
+            };
             return {
               artifacts: { manifests: artifacts2.manifests },
-              output: artifacts2.output
+              output: output2,
+              result: result2
             };
           } catch (error) {
             boundaryDiagnostics ??= takeActionBoundaryDiagnostics(timeout.signal);
@@ -21582,7 +21789,7 @@ var OpensteerSessionRuntime = class {
           documentEpoch: output.screenshot.documentEpoch
         })
       });
-      return output;
+      return result;
     } catch (error) {
       await this.appendTrace({
         operation: "computer.execute",
@@ -21730,8 +21937,9 @@ var OpensteerSessionRuntime = class {
           mutationCaptureDiagnostics = diagnostics;
         }
       );
-      const output = toOpensteerActionResult(executed.result);
+      const output = toOpensteerActionResult(executed.result.resolved);
       const actionEvents = "events" in executed.result ? executed.result.events : void 0;
+      const resolvedTarget = toOpensteerResolvedTarget2(executed.result.resolved);
       await this.appendTrace({
         operation,
         startedAt,
@@ -21739,8 +21947,13 @@ var OpensteerSessionRuntime = class {
         outcome: "ok",
         ...actionEvents === void 0 ? {} : { events: actionEvents },
         data: {
-          target: output.target,
-          ...output.point === void 0 ? {} : { point: output.point },
+          target: resolvedTarget,
+          ..."point" in executed.result && executed.result.point !== void 0 ? {
+            point: {
+              x: executed.result.point.x,
+              y: executed.result.point.y
+            }
+          } : {},
           ...boundaryDiagnostics === void 0 ? {} : { settle: boundaryDiagnostics },
           ...buildMutationCaptureTraceData(mutationCaptureDiagnostics)
         },
@@ -23205,20 +23418,20 @@ var OpensteerSessionRuntime = class {
       throw error;
     }
   }
-  async readSessionState() {
-    const pageRef = await this.ensurePageRef();
+  async readNavigationSummary(targetPageRef) {
+    const pageRef = targetPageRef ?? await this.ensurePageRef();
     const pageInfo = await this.requireEngine().getPageInfo({ pageRef });
-    const sessionRef = this.sessionRef;
-    if (!sessionRef) {
-      throw new Error("Opensteer session is not initialized");
-    }
     return {
-      sessionRef,
-      pageRef,
       url: pageInfo.url,
       title: pageInfo.title
     };
   }
+  async readCreatedPageOutput(pageRef) {
+    return {
+      pageRef,
+      ...await this.readNavigationSummary(pageRef)
+    };
+  }
   async captureSnapshotArtifacts(pageRef, options, timeout) {
     const root = this.requireRoot();
     const mainFrame = await timeout.runStep(() => getMainFrame(this.requireEngine(), pageRef));
@@ -23290,12 +23503,12 @@ var OpensteerSessionRuntime = class {
     const screenshotPayload = manifestToExternalBinaryLocation(root.rootPath, screenshotManifest);
     return {
       manifests,
-      output: {
-        ...output,
-        screenshot: {
-          ...output.screenshot,
-          payload: screenshotPayload
-        }
+      screenshot: {
+        payload: screenshotPayload,
+        format: output.screenshot.format,
+        size: output.screenshot.size,
+        coordinateSpace: output.screenshot.coordinateSpace,
+        ...output.screenshot.clip === void 0 ? {} : { clip: output.screenshot.clip }
       }
     };
   }
@@ -24818,15 +25031,10 @@ function normalizeNamespace2(value) {
   const normalized = String(value ?? "default").trim();
   return normalized.length === 0 ? "default" : normalized;
 }
-function toOpensteerActionResult(result) {
+function toOpensteerActionResult(target) {
   return {
-    target: toOpensteerResolvedTarget2(result.resolved),
-    ...result.point === void 0 ? {} : {
-      point: {
-        x: result.point.x,
-        y: result.point.y
-      }
-    }
+    tagName: toOpensteerTagName2(target.node.nodeName),
+    ...target.persist === void 0 ? {} : { persist: target.persist }
   };
 }
 function toOpensteerResolvedTarget2(target) {
@@ -24836,14 +25044,18 @@ function toOpensteerResolvedTarget2(target) {
     documentRef: target.documentRef,
     documentEpoch: target.documentEpoch,
     nodeRef: target.nodeRef,
-    tagName: target.node.nodeName.toUpperCase(),
+    tagName: toOpensteerTagName2(target.node.nodeName),
     pathHint: buildPathSelectorHint(target.replayPath ?? target.anchor),
     ...target.persist === void 0 ? {} : { persist: target.persist },
     ...target.selectorUsed === void 0 ? {} : { selectorUsed: target.selectorUsed }
   };
 }
+function toOpensteerTagName2(nodeName) {
+  const tagName = String(nodeName).trim().toLowerCase();
+  return tagName.length === 0 ? "element" : tagName;
+}
 function normalizeOpensteerError(error) {
-  return normalizeThrownOpensteerError(error, "Unknown Opensteer runtime failure");
+  return normalizeThrownOpensteerError2(error, "Unknown Opensteer runtime failure");
 }
 function observationArtifactKindFromManifest(kind) {
   switch (kind) {
@@ -25543,6 +25755,7 @@ function payloadByteLength(value) {
 
 // src/cloud/session-proxy.ts
 var TEMPORARY_CLOUD_WORKSPACE_PREFIX = "opensteer-cloud-workspace-";
+var CLOUD_SESSION_REUSE_EXPIRY_SKEW_MS = 1e4;
 var CloudSessionProxy = class {
   rootPath;
   workspace;
@@ -25556,6 +25769,8 @@ var CloudSessionProxy = class {
   automation;
   workspaceStore;
   syncWorkspaceOnClose = false;
+  liveSessionStateEstablished = false;
+  storedInstrumentation = [];
   constructor(cloud, options = {}) {
     this.cloud = cloud;
     this.workspace = options.workspace;
@@ -25585,15 +25800,12 @@ var CloudSessionProxy = class {
     if (this.client === void 0 && this.sessionId === void 0 && persisted !== void 0 && await this.isReusableCloudSession(persisted.sessionId)) {
       this.bindClient(persisted);
     }
-    if (this.automation) {
-      try {
-        const sessionInfo = await this.automation.getSessionInfo();
-        return {
-          ...sessionInfo,
-          ...this.workspace === void 0 ? {} : { workspace: this.workspace }
-        };
-      } catch {
-      }
+    const sessionInfo = this.automation ? await this.automation.getSessionInfo().catch(() => void 0) : void 0;
+    if (sessionInfo !== void 0) {
+      return {
+        ...sessionInfo,
+        ...this.workspace === void 0 ? {} : { workspace: this.workspace }
+      };
     }
     return {
       provider: {
@@ -25705,12 +25917,26 @@ var CloudSessionProxy = class {
     return this.invokeSemanticOperation("session.cookies", input);
   }
   async route(input) {
-    await this.ensureSession();
-    return this.requireAutomation().route(input);
+    const registration = await this.invokeBootstrapInstrumentationOperation(
+      "instrumentation.route",
+      (automation) => automation.route(input)
+    );
+    this.storedInstrumentation.push({
+      kind: "route",
+      input
+    });
+    return registration;
   }
   async interceptScript(input) {
-    await this.ensureSession();
-    return this.requireAutomation().interceptScript(input);
+    const registration = await this.invokeBootstrapInstrumentationOperation(
+      "instrumentation.intercept-script",
+      (automation) => automation.interceptScript(input)
+    );
+    this.storedInstrumentation.push({
+      kind: "intercept-script",
+      input
+    });
+    return registration;
   }
   async getStorageSnapshot(input = {}) {
     return this.invokeSemanticOperation("session.storage", input);
@@ -25758,6 +25984,8 @@ var CloudSessionProxy = class {
       this.client = void 0;
       this.sessionId = void 0;
       this.semanticGrant = void 0;
+      this.liveSessionStateEstablished = false;
+      this.storedInstrumentation.length = 0;
       if (this.cleanupRootOnClose) {
         await promises.rm(this.rootPath, { recursive: true, force: true }).catch(() => void 0);
       }
@@ -25785,6 +26013,8 @@ var CloudSessionProxy = class {
     this.automation = void 0;
     this.sessionId = void 0;
     this.semanticGrant = void 0;
+    this.liveSessionStateEstablished = false;
+    this.storedInstrumentation.length = 0;
     if (syncError !== void 0) {
       throw syncError;
     }
@@ -25832,6 +26062,7 @@ var CloudSessionProxy = class {
     };
     await this.writePersistedSession(record);
     this.bindClient(record, session.initialGrants?.semantic);
+    await this.restoreStoredInstrumentation();
   }
   async syncWorkspaceToCloud() {
     if (this.workspace === void 0) {
@@ -25843,6 +26074,7 @@ var CloudSessionProxy = class {
   bindClient(record, initialSemanticGrant) {
     this.sessionId = record.sessionId;
     this.semanticGrant = initialSemanticGrant?.kind === "semantic" ? initialSemanticGrant : void 0;
+    this.liveSessionStateEstablished = false;
     this.client = new OpensteerSemanticRestClient({
       getBaseUrl: async () => (await this.ensureSemanticGrant()).url,
       getAuthorizationHeader: async () => `Bearer ${(await this.ensureSemanticGrant()).token}`,
@@ -25850,6 +26082,19 @@ var CloudSessionProxy = class {
     });
     this.automation = new OpensteerCloudAutomationClient(this.cloud, record.sessionId);
   }
+  async restoreStoredInstrumentation() {
+    if (this.storedInstrumentation.length === 0) {
+      return;
+    }
+    const automation = this.requireAutomation();
+    for (const registration of this.storedInstrumentation) {
+      if (registration.kind === "route") {
+        await automation.route(registration.input);
+      } else {
+        await automation.interceptScript(registration.input);
+      }
+    }
+  }
   async ensureWorkspaceStore() {
     if (this.workspaceStore !== void 0) {
       return this.workspaceStore;
@@ -25872,13 +26117,22 @@ var CloudSessionProxy = class {
   async clearPersistedSession() {
     await clearPersistedSessionRecord(this.rootPath, "cloud").catch(() => void 0);
   }
+  async invalidateSession() {
+    await this.automation?.close().catch(() => void 0);
+    this.automation = void 0;
+    this.client = void 0;
+    this.sessionId = void 0;
+    this.semanticGrant = void 0;
+    this.liveSessionStateEstablished = false;
+    await this.clearPersistedSession();
+  }
   async isReusableCloudSession(sessionId, timeout) {
     try {
       const session = await this.cloud.getSession(sessionId, {
         signal: timeout?.signal,
         timeoutMs: timeout?.remainingMs()
       });
-      return session.status !== "closed" && session.status !== "failed";
+      return isReusableCloudSessionState(session);
     } catch (error) {
       if (isMissingCloudSessionError(error)) {
         return false;
@@ -25927,26 +26181,79 @@ var CloudSessionProxy = class {
     try {
       await this.ensureSemanticGrant(true);
       return true;
-    } catch {
+    } catch (refreshError) {
+      if (await this.resetStaleSession(refreshError)) {
+        throw refreshError;
+      }
       return false;
     }
   }
   async invokeSemanticOperation(operation, input, sessionInit = {}) {
-    return this.runOperationWithPolicy(operation, async (timeout) => {
+    return this.runOperationWithSessionRecovery(operation, async (timeout) => {
       await this.ensureSession(sessionInit, timeout);
       await this.ensureSemanticGrant(false, timeout);
-      return this.requireClient().invoke(operation, input, {
+      const output = await this.requireClient().invoke(operation, input, {
         signal: timeout.signal,
         timeoutMs: timeout.remainingMs()
       });
+      this.noteSuccessfulLiveOperation(operation);
+      return output;
     });
   }
   async invokeAutomationOperation(operation, invoke, sessionInit = {}) {
-    return this.runOperationWithPolicy(operation, async (timeout) => {
+    return this.runOperationWithSessionRecovery(operation, async (timeout) => {
       await this.ensureSession(sessionInit, timeout);
-      return invoke(this.requireAutomation());
+      const output = await invoke(this.requireAutomation());
+      this.noteSuccessfulLiveOperation(operation);
+      return output;
+    });
+  }
+  async invokeBootstrapInstrumentationOperation(operation, invoke) {
+    let recovered = false;
+    while (true) {
+      try {
+        await this.ensureSession();
+        return await invoke(this.requireAutomation());
+      } catch (error) {
+        const stale = await this.resetStaleSession(error);
+        if (!stale || recovered || !this.canRecoverWithFreshSession(operation)) {
+          throw error;
+        }
+        recovered = true;
+      }
+    }
+  }
+  async runOperationWithSessionRecovery(operation, invoke) {
+    return this.runOperationWithPolicy(operation, async (timeout) => {
+      let recovered = false;
+      while (true) {
+        try {
+          return await invoke(timeout);
+        } catch (error) {
+          const stale = await this.resetStaleSession(error);
+          if (!stale || recovered || !this.canRecoverWithFreshSession(operation)) {
+            throw error;
+          }
+          recovered = true;
+        }
+      }
     });
   }
+  async resetStaleSession(error) {
+    if (!isRecoverableCloudSessionError(error)) {
+      return false;
+    }
+    await this.invalidateSession();
+    return true;
+  }
+  canRecoverWithFreshSession(operation) {
+    return !this.liveSessionStateEstablished && isBootstrapRecoveryOperation(operation);
+  }
+  noteSuccessfulLiveOperation(operation) {
+    if (operation === "session.open" || operation === "page.list" || operation === "page.new" || operation === "page.activate" || operation === "page.close" || operation === "page.goto" || operation === "page.evaluate" || operation === "page.add-init-script" || operation === "page.snapshot" || operation === "dom.click" || operation === "dom.hover" || operation === "dom.input" || operation === "dom.scroll" || operation === "dom.extract" || operation === "network.query" || operation === "network.detail" || operation === "interaction.capture" || operation === "interaction.get" || operation === "interaction.diff" || operation === "interaction.replay" || operation === "scripts.capture" || operation === "artifact.read" || operation === "scripts.beautify" || operation === "scripts.deobfuscate" || operation === "scripts.sandbox" || operation === "captcha.solve" || operation === "session.cookies" || operation === "session.storage" || operation === "session.state" || operation === "session.fetch" || operation === "computer.execute") {
+      this.liveSessionStateEstablished = true;
+    }
+  }
   async runOperationWithPolicy(operation, invoke) {
     return runWithPolicyTimeout(this.policy.timeout, { operation }, invoke);
   }
@@ -25970,8 +26277,29 @@ function assertSupportedCloudBrowserMode(browser) {
   }
 }
 function isMissingCloudSessionError(error) {
+  if (error instanceof OpensteerCloudRequestError) {
+    return error.statusCode === 404 && (error.code === void 0 || error.code === "CLOUD_SESSION_NOT_FOUND");
+  }
   return error instanceof Error && /\b404\b/.test(error.message);
 }
+function isRecoverableCloudSessionError(error) {
+  if (!(error instanceof OpensteerCloudRequestError)) {
+    return false;
+  }
+  if (error.statusCode === 404) {
+    return error.code === void 0 || error.code === "CLOUD_SESSION_NOT_FOUND";
+  }
+  return error.statusCode === 409 && error.code === "CLOUD_SESSION_STALE";
+}
+function isBootstrapRecoveryOperation(operation) {
+  return operation === "session.open" || operation === "instrumentation.route" || operation === "instrumentation.intercept-script";
+}
+function isReusableCloudSessionState(session) {
+  if (session.status === "closing" || session.status === "closed" || session.status === "failed") {
+    return false;
+  }
+  return !(typeof session.expiresAt === "number" && session.expiresAt <= Date.now() + CLOUD_SESSION_REUSE_EXPIRY_SKEW_MS);
+}
 function isLoopbackBaseUrl(baseUrl) {
   let url;
   try {
@@ -26133,6 +26461,25 @@ var SessionCookieJar = class {
     return this.cookies.map((cookie) => `${cookie.name}=${cookie.value}`).join("; ");
   }
 };
+function createSdkProtocolError(error, fallbackMessage) {
+  const normalized = normalizeThrownOpensteerError(error, fallbackMessage);
+  return new OpensteerProtocolError(normalized.code, normalized.message, {
+    cause: error,
+    retriable: normalized.retriable,
+    ...normalized.capability === void 0 ? {} : { capability: normalized.capability },
+    ...normalized.details === void 0 ? {} : { details: normalized.details }
+  });
+}
+async function wrapSdkError(operation, fn) {
+  try {
+    return await fn();
+  } catch (error) {
+    if (isOpensteerProtocolError(error)) {
+      throw error;
+    }
+    throw createSdkProtocolError(error, `${operation} failed`);
+  }
+}
 var Opensteer = class {
   runtime;
   browserManager;
@@ -26140,207 +26487,265 @@ var Opensteer = class {
   dom;
   network;
   constructor(options = {}) {
-    const environment = resolveOpensteerEnvironment(options.rootDir);
-    const { provider, engineName, ...runtimeOptions } = options;
-    const runtimeConfig = resolveOpensteerRuntimeConfig({
-      ...provider === void 0 ? {} : { provider },
-      environment
-    });
-    if (runtimeConfig.provider.mode === "cloud") {
-      this.browserManager = void 0;
-      this.runtime = createOpensteerSemanticRuntime({
-        ...provider === void 0 ? {} : { provider },
-        ...engineName === void 0 ? {} : { engine: engineName },
-        environment,
-        runtimeOptions
-      });
-      this.browser = createUnsupportedBrowserController();
-    } else {
-      this.browserManager = new OpensteerBrowserManager({
-        ...runtimeOptions.rootDir === void 0 ? {} : { rootDir: runtimeOptions.rootDir },
-        ...runtimeOptions.rootPath === void 0 ? {} : { rootPath: runtimeOptions.rootPath },
-        ...runtimeOptions.workspace === void 0 ? {} : { workspace: runtimeOptions.workspace },
-        ...engineName === void 0 ? {} : { engineName },
-        environment,
-        ...runtimeOptions.browser === void 0 ? {} : { browser: runtimeOptions.browser },
-        ...runtimeOptions.launch === void 0 ? {} : { launch: runtimeOptions.launch },
-        ...runtimeOptions.context === void 0 ? {} : { context: runtimeOptions.context }
-      });
-      this.runtime = createOpensteerSemanticRuntime({
+    try {
+      const environment = resolveOpensteerEnvironment(options.rootDir);
+      const { provider, engineName, ...runtimeOptions } = options;
+      const runtimeConfig = resolveOpensteerRuntimeConfig({
         ...provider === void 0 ? {} : { provider },
-        ...engineName === void 0 ? {} : { engine: engineName },
-        environment,
-        runtimeOptions: {
-          ...runtimeOptions,
-          rootPath: this.browserManager.rootPath,
-          cleanupRootOnClose: this.browserManager.cleanupRootOnDisconnect
-        }
+        environment
       });
-      this.browser = {
-        status: () => this.browserManager.status(),
-        clone: (input) => this.browserManager.clonePersistentBrowser(input),
-        reset: () => this.browserManager.reset(),
-        delete: () => this.browserManager.delete()
+      if (runtimeConfig.provider.mode === "cloud") {
+        this.browserManager = void 0;
+        this.runtime = createOpensteerSemanticRuntime({
+          ...provider === void 0 ? {} : { provider },
+          ...engineName === void 0 ? {} : { engine: engineName },
+          environment,
+          runtimeOptions
+        });
+        this.browser = createUnsupportedBrowserController();
+      } else {
+        this.browserManager = new OpensteerBrowserManager({
+          ...runtimeOptions.rootDir === void 0 ? {} : { rootDir: runtimeOptions.rootDir },
+          ...runtimeOptions.rootPath === void 0 ? {} : { rootPath: runtimeOptions.rootPath },
+          ...runtimeOptions.workspace === void 0 ? {} : { workspace: runtimeOptions.workspace },
+          ...engineName === void 0 ? {} : { engineName },
+          environment,
+          ...runtimeOptions.browser === void 0 ? {} : { browser: runtimeOptions.browser },
+          ...runtimeOptions.launch === void 0 ? {} : { launch: runtimeOptions.launch },
+          ...runtimeOptions.context === void 0 ? {} : { context: runtimeOptions.context }
+        });
+        this.runtime = createOpensteerSemanticRuntime({
+          ...provider === void 0 ? {} : { provider },
+          ...engineName === void 0 ? {} : { engine: engineName },
+          environment,
+          runtimeOptions: {
+            ...runtimeOptions,
+            rootPath: this.browserManager.rootPath,
+            cleanupRootOnClose: this.browserManager.cleanupRootOnDisconnect
+          }
+        });
+        this.browser = {
+          status: () => wrapSdkError("browser.status", () => this.browserManager.status()),
+          clone: (input) => wrapSdkError("browser.clone", () => this.browserManager.clonePersistentBrowser(input)),
+          reset: () => wrapSdkError("browser.reset", () => this.browserManager.reset()),
+          delete: () => wrapSdkError("browser.delete", () => this.browserManager.delete())
+        };
+      }
+      this.dom = {
+        click: (input) => this.click(input),
+        hover: (input) => this.hover(input),
+        input: (input) => this.input(input),
+        scroll: (input) => this.scroll(input)
       };
+      this.network = {
+        query: (input = {}) => wrapSdkError("network.query", () => this.runtime.queryNetwork(input)),
+        detail: (recordId, options2) => wrapSdkError(
+          "network.detail",
+          () => this.runtime.getNetworkDetail({ recordId, ...options2 })
+        )
+      };
+    } catch (error) {
+      if (isOpensteerProtocolError(error)) {
+        throw error;
+      }
+      throw createSdkProtocolError(error, "Failed to initialize Opensteer");
     }
-    this.dom = {
-      click: (input) => this.click(input),
-      hover: (input) => this.hover(input),
-      input: (input) => this.input(input),
-      scroll: (input) => this.scroll(input)
-    };
-    this.network = {
-      query: (input = {}) => this.runtime.queryNetwork(input),
-      detail: (recordId, options2) => this.runtime.getNetworkDetail({ recordId, ...options2 })
-    };
   }
   async open(input = {}) {
-    return this.runtime.open(typeof input === "string" ? { url: input } : input);
+    return wrapSdkError(
+      "session.open",
+      () => this.runtime.open(typeof input === "string" ? { url: input } : input)
+    );
   }
   async info() {
-    return this.runtime.info();
+    return wrapSdkError("session.info", () => this.runtime.info());
   }
   async listPages(input = {}) {
-    return this.runtime.listPages(input);
+    return wrapSdkError("page.list", () => this.runtime.listPages(input));
   }
   async newPage(input = {}) {
-    return this.runtime.newPage(input);
+    return wrapSdkError("page.new", () => this.runtime.newPage(input));
   }
   async activatePage(input) {
-    return this.runtime.activatePage(input);
+    return wrapSdkError("page.activate", () => this.runtime.activatePage(input));
   }
   async closePage(input = {}) {
-    return this.runtime.closePage(input);
+    return wrapSdkError("page.close", () => this.runtime.closePage(input));
   }
   async goto(url, options = {}) {
-    return this.runtime.goto({
-      url,
-      ...options
-    });
+    return wrapSdkError(
+      "page.goto",
+      () => this.runtime.goto({
+        url,
+        ...options
+      })
+    );
   }
   async evaluate(input) {
-    const normalized = typeof input === "string" ? {
-      script: input
-    } : input;
-    return (await this.runtime.evaluate(normalized)).value;
+    return wrapSdkError("page.evaluate", async () => {
+      const normalized = typeof input === "string" ? {
+        script: input
+      } : input;
+      return (await this.runtime.evaluate(normalized)).value;
+    });
   }
   async addInitScript(input) {
-    return this.runtime.addInitScript(
-      typeof input === "string" ? {
-        script: input
-      } : input
+    return wrapSdkError(
+      "page.addInitScript",
+      () => this.runtime.addInitScript(
+        typeof input === "string" ? {
+          script: input
+        } : input
+      )
     );
   }
   async click(input) {
-    const { button, clickCount, modifiers, ...target } = input;
-    return this.runtime.click({
-      ...normalizeTargetOptions(target),
-      ...button === void 0 ? {} : { button },
-      ...clickCount === void 0 ? {} : { clickCount },
-      ...modifiers === void 0 ? {} : { modifiers }
+    return wrapSdkError("dom.click", () => {
+      const { button, clickCount, modifiers, ...target } = input;
+      return this.runtime.click({
+        ...normalizeTargetOptions(target),
+        ...button === void 0 ? {} : { button },
+        ...clickCount === void 0 ? {} : { clickCount },
+        ...modifiers === void 0 ? {} : { modifiers }
+      });
     });
   }
   async hover(input) {
-    return this.runtime.hover(normalizeTargetOptions(input));
+    return wrapSdkError("dom.hover", () => this.runtime.hover(normalizeTargetOptions(input)));
   }
   async input(input) {
-    return this.runtime.input({
-      ...normalizeTargetOptions(input),
-      text: input.text,
-      ...input.pressEnter === void 0 ? {} : { pressEnter: input.pressEnter }
-    });
+    return wrapSdkError(
+      "dom.input",
+      () => this.runtime.input({
+        ...normalizeTargetOptions(input),
+        text: input.text,
+        ...input.pressEnter === void 0 ? {} : { pressEnter: input.pressEnter }
+      })
+    );
   }
   async scroll(input) {
-    return this.runtime.scroll({
-      ...normalizeTargetOptions(input),
-      direction: input.direction,
-      amount: input.amount
-    });
+    return wrapSdkError(
+      "dom.scroll",
+      () => this.runtime.scroll({
+        ...normalizeTargetOptions(input),
+        direction: input.direction,
+        amount: input.amount
+      })
+    );
   }
   async extract(input) {
-    return (await this.runtime.extract(input)).data;
+    return wrapSdkError("extract", async () => (await this.runtime.extract(input)).data);
   }
   async waitForPage(input = {}) {
-    const baseline = new Set((await this.runtime.listPages()).pages.map((page) => page.pageRef));
-    const timeoutAt = Date.now() + (input.timeoutMs ?? 3e4);
-    const pollIntervalMs = input.pollIntervalMs ?? 100;
-    while (true) {
-      const match = (await this.runtime.listPages()).pages.find((page) => {
-        if (baseline.has(page.pageRef)) {
-          return false;
-        }
-        if (input.openerPageRef !== void 0 && page.openerPageRef !== input.openerPageRef) {
-          return false;
+    return wrapSdkError("page.waitForPage", async () => {
+      const baseline = new Set((await this.runtime.listPages()).pages.map((page) => page.pageRef));
+      const timeoutAt = Date.now() + (input.timeoutMs ?? 3e4);
+      const pollIntervalMs = input.pollIntervalMs ?? 100;
+      while (true) {
+        const match = (await this.runtime.listPages()).pages.find((page) => {
+          if (baseline.has(page.pageRef)) {
+            return false;
+          }
+          if (input.openerPageRef !== void 0 && page.openerPageRef !== input.openerPageRef) {
+            return false;
+          }
+          if (input.urlIncludes !== void 0 && !page.url.includes(input.urlIncludes)) {
+            return false;
+          }
+          return true;
+        });
+        if (match !== void 0) {
+          return match;
         }
-        if (input.urlIncludes !== void 0 && !page.url.includes(input.urlIncludes)) {
-          return false;
+        if (Date.now() >= timeoutAt) {
+          throw new OpensteerProtocolError("timeout", "waitForPage timed out");
         }
-        return true;
-      });
-      if (match !== void 0) {
-        return match;
-      }
-      if (Date.now() >= timeoutAt) {
-        throw new Error("waitForPage timed out");
+        await delay3(pollIntervalMs);
       }
-      await delay3(pollIntervalMs);
-    }
+    });
   }
   async cookies(domain) {
-    return new SessionCookieJar(
-      await this.runtime.getCookies(domain === void 0 ? {} : { domain })
+    return wrapSdkError(
+      "session.cookies",
+      async () => new SessionCookieJar(await this.runtime.getCookies(domain === void 0 ? {} : { domain }))
     );
   }
   async storage(domain, type = "local") {
-    const snapshot = await this.runtime.getStorageSnapshot(domain === void 0 ? {} : { domain });
-    const domainSnapshot = pickStorageDomainSnapshot(snapshot, domain);
-    if (domainSnapshot === void 0) {
-      return {};
-    }
-    const entries = type === "local" ? domainSnapshot.localStorage : domainSnapshot.sessionStorage;
-    return Object.fromEntries(entries.map((entry) => [entry.key, entry.value]));
+    return wrapSdkError("session.storage", async () => {
+      const snapshot = await this.runtime.getStorageSnapshot(
+        domain === void 0 ? {} : { domain }
+      );
+      const domainSnapshot = pickStorageDomainSnapshot(snapshot, domain);
+      if (domainSnapshot === void 0) {
+        return {};
+      }
+      const entries = type === "local" ? domainSnapshot.localStorage : domainSnapshot.sessionStorage;
+      return Object.fromEntries(entries.map((entry) => [entry.key, entry.value]));
+    });
   }
   async state(domain) {
-    return this.runtime.getBrowserState(domain === void 0 ? {} : { domain });
+    return wrapSdkError(
+      "session.state",
+      () => this.runtime.getBrowserState(domain === void 0 ? {} : { domain })
+    );
   }
   async fetch(url, options = {}) {
-    const input = buildFetchInput(url, options);
-    const result = await this.runtime.fetch(input);
-    if (result.response === void 0) {
-      throw new Error(result.note ?? `session.fetch did not produce a response for ${url}`);
-    }
-    return toResponse(result.response);
+    return wrapSdkError("session.fetch", async () => {
+      const input = buildFetchInput(url, options);
+      const result = await this.runtime.fetch(input);
+      if (result.response === void 0) {
+        throw new OpensteerProtocolError(
+          "operation-failed",
+          result.note ?? `session.fetch did not produce a response for ${url}`
+        );
+      }
+      return toResponse(result.response);
+    });
   }
   async computerExecute(input) {
-    return this.runtime.computerExecute(input);
+    return wrapSdkError("session.computerExecute", () => this.runtime.computerExecute(input));
   }
   async route(input) {
-    return this.requireOwnedInstrumentationRuntime("route").route(input);
+    return wrapSdkError(
+      "session.route",
+      () => this.requireOwnedInstrumentationRuntime("route").route(input)
+    );
   }
   async interceptScript(input) {
-    return this.requireOwnedInstrumentationRuntime("interceptScript").interceptScript(input);
+    return wrapSdkError(
+      "session.interceptScript",
+      () => this.requireOwnedInstrumentationRuntime("interceptScript").interceptScript(input)
+    );
   }
   async close() {
-    if (this.browserManager === void 0 || this.browserManager.mode === "temporary") {
-      return this.runtime.close();
-    }
-    const output = await this.runtime.close();
-    await this.browserManager.close();
-    return output;
+    return wrapSdkError("session.close", async () => {
+      if (this.browserManager === void 0 || this.browserManager.mode === "temporary") {
+        return this.runtime.close();
+      }
+      const output = await this.runtime.close();
+      await this.browserManager.close();
+      return output;
+    });
   }
   async disconnect() {
-    await this.runtime.disconnect();
+    return wrapSdkError("session.disconnect", () => this.runtime.disconnect());
   }
   requireOwnedInstrumentationRuntime(method) {
     if (typeof this.runtime.route === "function" && typeof this.runtime.interceptScript === "function") {
       return this.runtime;
     }
-    throw new Error(`${method}() is not available for this session runtime.`);
+    throw new OpensteerProtocolError(
+      "unsupported-operation",
+      `${method}() is not available for this session runtime.`
+    );
   }
 };
 function createUnsupportedBrowserController() {
   const fail = async () => {
-    throw new Error("browser.* helpers are only available in local mode.");
+    throw new OpensteerProtocolError(
+      "unsupported-operation",
+      "browser.* helpers are only available in local mode."
+    );
   };
   return {
     status: fail,
@@ -26353,7 +26758,10 @@ function normalizeTargetOptions(input) {
   const hasElement = input.element !== void 0;
   const hasSelector = input.selector !== void 0;
   if (hasElement && hasSelector) {
-    throw new Error("Specify exactly one of element, selector, or persist.");
+    throw new OpensteerProtocolError(
+      "invalid-argument",
+      "Specify exactly one of element, selector, or persist."
+    );
   }
   if (hasElement) {
     return {
@@ -26376,7 +26784,10 @@ function normalizeTargetOptions(input) {
     };
   }
   if (input.persist === void 0) {
-    throw new Error("Specify exactly one of element, selector, or persist.");
+    throw new OpensteerProtocolError(
+      "invalid-argument",
+      "Specify exactly one of element, selector, or persist."
+    );
   }
   return {
     target: {
@@ -26448,6 +26859,7 @@ exports.Opensteer = Opensteer;
 exports.OpensteerAttachAmbiguousError = OpensteerAttachAmbiguousError;
 exports.OpensteerBrowserManager = OpensteerBrowserManager;
 exports.OpensteerCloudClient = OpensteerCloudClient;
+exports.OpensteerProtocolError = OpensteerProtocolError;
 exports.STABLE_PRIMARY_ATTR_KEYS = STABLE_PRIMARY_ATTR_KEYS;
 exports.assertProviderSupportsEngine = assertProviderSupportsEngine;
 exports.buildArrayFieldPathCandidates = buildArrayFieldPathCandidates;
@@ -26477,6 +26889,7 @@ exports.discoverLocalCdpBrowsers = discoverLocalCdpBrowsers;
 exports.hashDomDescriptorPersist = hashDomDescriptorPersist;
 exports.inspectCdpEndpoint = inspectCdpEndpoint;
 exports.isCurrentUrlField = isCurrentUrlField;
+exports.isOpensteerProtocolError = isOpensteerProtocolError;
 exports.isValidCssAttributeKey = isValidCssAttributeKey;
 exports.listLocalChromeProfiles = listLocalChromeProfiles;
 exports.manifestToExternalBinaryLocation = manifestToExternalBinaryLocation;
@@ -26485,6 +26898,7 @@ exports.normalizeObservabilityConfig = normalizeObservabilityConfig;
 exports.normalizeOpensteerEngineName = normalizeOpensteerEngineName;
 exports.normalizeOpensteerProviderMode = normalizeOpensteerProviderMode;
 exports.normalizeWorkspaceId = normalizeWorkspaceId;
+exports.opensteerErrorCodes = opensteerErrorCodes;
 exports.parseDomDescriptorRecord = parseDomDescriptorRecord;
 exports.parseExtractionDescriptorRecord = parseExtractionDescriptorRecord;
 exports.readPersistedCloudSessionRecord = readPersistedCloudSessionRecord;