opensteer 0.9.5 → 0.9.6

package/dist/{chunk-7LQL5YUR.js → chunk-BVRIPCWA.js}

@@ -1,4 +1,4 @@
-import { resolveFilesystemWorkspacePath, createFilesystemOpensteerWorkspace, DEFAULT_OPENSTEER_ENGINE, assertSupportedEngineOptions, normalizeObservabilityConfig, manifestToExternalBinaryLocation, normalizeObservationContext, OpensteerBrowserManager } from './chunk-GSCQQKZZ.js';
+import { objectSchema, stringSchema, literalSchema, JSON_SCHEMA_DRAFT_2020_12, integerSchema, enumSchema, oneOfSchema, numberSchema, arraySchema, recordSchema, defineSchema, opensteerCapabilitySetSchema, opensteerErrorSchema, OpensteerProtocolError, resolveFilesystemWorkspacePath, createFilesystemOpensteerWorkspace, DEFAULT_OPENSTEER_ENGINE, createOpensteerError, assertSupportedEngineOptions, normalizeObservabilityConfig, manifestToExternalBinaryLocation, normalizeObservationContext, OpensteerBrowserManager, isOpensteerProtocolError, toOpensteerError } from './chunk-3XBQRZZC.js';
 import { canonicalJsonString, toCanonicalJsonValue, readPersistedCloudSessionRecord, writePersistedSessionRecord, clearPersistedSessionRecord, resolveBrandUserDataDir, sha256Hex, getBrowserBrand, detectInstalledBrowserBrands, __require } from './chunk-T5P2QGZ3.js';
 import { selectAll } from 'css-select';
 import { createHash, randomUUID, pbkdf2Sync, createDecipheriv } from 'crypto';
@@ -208,9 +208,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;
 
@@ -240,21 +237,6 @@ 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 },
@@ -333,7 +315,6 @@ var defaultNavigationSettleObserver = {
 };
 Object.freeze(defaultNavigationSettleObserver);
 var DEFAULT_SETTLE_OBSERVERS = Object.freeze([
-  defaultSnapshotSettleObserver,
   defaultDomActionSettleObserver,
   defaultNavigationSettleObserver
 ]);
@@ -412,72 +393,6 @@ function abortError() {
   return error;
 }
 
-// ../protocol/src/json.ts
-var JSON_SCHEMA_DRAFT_2020_12 = "https://json-schema.org/draft/2020-12/schema";
-function defineSchema(schema) {
-  return schema;
-}
-function stringSchema(options = {}) {
-  return defineSchema({
-    type: "string",
-    ...options
-  });
-}
-function numberSchema(options = {}) {
-  return defineSchema({
-    type: "number",
-    ...options
-  });
-}
-function integerSchema(options = {}) {
-  return defineSchema({
-    type: "integer",
-    ...options
-  });
-}
-function literalSchema(value, options = {}) {
-  return defineSchema({
-    const: value,
-    ...options
-  });
-}
-function enumSchema(values, options = {}) {
-  return defineSchema({
-    enum: values,
-    ...options
-  });
-}
-function arraySchema(items, options = {}) {
-  return defineSchema({
-    type: "array",
-    items,
-    ...options
-  });
-}
-function objectSchema(properties, options = {}) {
-  const { required, additionalProperties, ...rest } = options;
-  return defineSchema({
-    type: "object",
-    properties,
-    ...rest,
-    ...required === void 0 ? {} : { required },
-    ...additionalProperties === void 0 ? { additionalProperties: false } : { additionalProperties }
-  });
-}
-function recordSchema(valueSchema, options = {}) {
-  return defineSchema({
-    type: "object",
-    additionalProperties: valueSchema,
-    ...options
-  });
-}
-function oneOfSchema(members, options = {}) {
-  return defineSchema({
-    oneOf: members,
-    ...options
-  });
-}
-
 // ../protocol/src/validation.ts
 function validateJsonSchema(schema, value, path6 = "$") {
   return validateSchemaNode(schema, value, path6);
@@ -2387,152 +2302,6 @@ var hitTestResultSchema = objectSchema(
   }
 );
 
-// ../protocol/src/capabilities.ts
-var opensteerCapabilities = [
-  "sessions.manage",
-  "pages.manage",
-  "pages.navigate",
-  "input.pointer",
-  "input.keyboard",
-  "input.touch",
-  "artifacts.screenshot",
-  "execution.pause",
-  "execution.resume",
-  "execution.freeze",
-  "inspect.pages",
-  "inspect.frames",
-  "inspect.html",
-  "inspect.domSnapshot",
-  "inspect.text",
-  "inspect.attributes",
-  "inspect.hitTest",
-  "inspect.viewportMetrics",
-  "inspect.network",
-  "inspect.networkBodies",
-  "inspect.cookies",
-  "inspect.localStorage",
-  "inspect.sessionStorage",
-  "inspect.indexedDb",
-  "transport.sessionHttp",
-  "instrumentation.initScripts",
-  "instrumentation.routing",
-  "events.pageLifecycle",
-  "events.dialog",
-  "events.download",
-  "events.chooser",
-  "events.worker",
-  "events.console",
-  "events.pageError",
-  "events.websocket",
-  "events.eventStream",
-  "events.executionState",
-  "surface.rest",
-  "surface.mcp"
-];
-var opensteerCapabilitySchema = enumSchema(opensteerCapabilities, {
-  title: "OpensteerCapability"
-});
-var opensteerCapabilitySetSchema = arraySchema(opensteerCapabilitySchema, {
-  title: "OpensteerCapabilitySet",
-  uniqueItems: true
-});
-var opensteerCapabilityDescriptorSchema = objectSchema(
-  {
-    key: opensteerCapabilitySchema,
-    description: stringSchema(),
-    stability: enumSchema(["stable", "experimental"])
-  },
-  {
-    title: "OpensteerCapabilityDescriptor",
-    required: ["key", "description", "stability"]
-  }
-);
-arraySchema(
-  opensteerCapabilityDescriptorSchema,
-  {
-    title: "OpensteerCapabilityDescriptorList",
-    uniqueItems: true
-  }
-);
-
-// ../protocol/src/errors.ts
-var opensteerErrorCodes = [
-  "invalid-request",
-  "invalid-argument",
-  "invalid-ref",
-  "unsupported-version",
-  "unsupported-operation",
-  "unsupported-capability",
-  "not-found",
-  "stale-node-ref",
-  "session-closed",
-  "page-closed",
-  "frame-detached",
-  "timeout",
-  "navigation-failed",
-  "permission-denied",
-  "conflict",
-  "profile-unavailable",
-  "auth-failure",
-  "auth-recovery-failed",
-  "browser-required",
-  "rate-limited",
-  "operation-failed",
-  "internal"
-];
-var OpensteerProtocolError = class extends Error {
-  code;
-  retriable;
-  capability;
-  details;
-  constructor(code, message, options = {}) {
-    super(message, { cause: options.cause });
-    this.name = "OpensteerProtocolError";
-    this.code = code;
-    this.retriable = options.retriable ?? false;
-    this.capability = options.capability;
-    this.details = options.details;
-  }
-};
-function createOpensteerError(code, message, options = {}) {
-  return {
-    code,
-    message,
-    retriable: options.retriable ?? false,
-    ...options.capability === void 0 ? {} : { capability: options.capability },
-    ...options.details === void 0 ? {} : { details: options.details }
-  };
-}
-function isOpensteerProtocolError(value) {
-  return value instanceof OpensteerProtocolError;
-}
-function toOpensteerError(error) {
-  return createOpensteerError(error.code, error.message, {
-    retriable: error.retriable,
-    ...error.capability === void 0 ? {} : { capability: error.capability },
-    ...error.details === void 0 ? {} : { details: error.details }
-  });
-}
-var opensteerErrorCodeSchema = {
-  title: "OpensteerErrorCode",
-  enum: opensteerErrorCodes
-};
-var opensteerErrorSchema = objectSchema(
-  {
-    code: opensteerErrorCodeSchema,
-    message: stringSchema(),
-    retriable: {
-      type: "boolean"
-    },
-    capability: opensteerCapabilitySchema,
-    details: recordSchema({})
-  },
-  {
-    title: "OpensteerError",
-    required: ["code", "message", "retriable"]
-  }
-);
-
 // ../protocol/src/events.ts
 function eventBaseSchema(kind) {
   return {
@@ -5110,6 +4879,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))})`;
@@ -5234,7 +5006,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) {
@@ -5811,9 +5583,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],
@@ -5833,6 +5613,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) {
@@ -5991,7 +5775,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 },
@@ -6046,6 +5836,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) });
+        }
       }
     }
   }
@@ -6411,7 +6208,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"
@@ -6898,11 +6695,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,
@@ -6916,8 +6714,7 @@ var DomActionExecutor = class {
         hitMissingFromSnapshot: !resolved.snapshot.nodes.some(
           (node) => node.nodeRef === hit.nodeRef
         )
-      },
-      true
+      }
     );
   }
   async resolveActionablePointerTarget(session, operation, resolved) {
@@ -7129,7 +6926,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));
@@ -7349,7 +7151,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 }
@@ -7367,11 +7169,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, {
@@ -7471,7 +7274,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 }
@@ -7642,19 +7445,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;
     }
@@ -8268,6 +8072,9 @@ function relaxPathForSingleSample(path6, mode) {
         }
         return !isLast;
       }
+      if (clause.kind === "text") {
+        return false;
+      }
       const key = String(clause.key || "").trim().toLowerCase();
       if (!key || !shouldKeepAttrForSingleSample(key)) {
         return false;
@@ -8370,9 +8177,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,
@@ -8778,6 +8587,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" });
@@ -9773,7 +9585,8 @@ function assertProviderSupportsEngine(provider, engine) {
     return;
   }
   if (provider === "cloud") {
-    throw new Error(
+    throw new OpensteerProtocolError(
+      "invalid-argument",
       "ABP is not supported for provider=cloud. Cloud provider currently requires Playwright."
     );
   }
@@ -9783,7 +9596,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}".`
   );
 }
@@ -10223,6 +10037,24 @@ async function sleep(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;
@@ -10398,7 +10230,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;
   }
@@ -10446,6 +10282,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 = {}) {
@@ -10621,7 +10487,7 @@ async function dispatchSemanticOperation(runtime, operation, input, options = {}
 
 // ../runtime-core/package.json
 var package_default = {
-  version: "0.2.4"};
+  version: "0.2.5"};
 
 // ../runtime-core/src/version.ts
 var OPENSTEER_RUNTIME_CORE_VERSION = package_default.version;
@@ -22224,6 +22090,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;
@@ -22237,6 +22104,8 @@ var CloudSessionProxy = class {
   automation;
   workspaceStore;
   syncWorkspaceOnClose = false;
+  liveSessionStateEstablished = false;
+  storedInstrumentation = [];
   constructor(cloud, options = {}) {
     this.cloud = cloud;
     this.workspace = options.workspace;
@@ -22266,15 +22135,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: {
@@ -22386,12 +22252,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);
@@ -22439,6 +22319,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 rm(this.rootPath, { recursive: true, force: true }).catch(() => void 0);
       }
@@ -22466,6 +22348,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;
     }
@@ -22513,6 +22397,7 @@ var CloudSessionProxy = class {
     };
     await this.writePersistedSession(record);
     this.bindClient(record, session.initialGrants?.semantic);
+    await this.restoreStoredInstrumentation();
   }
   async syncWorkspaceToCloud() {
     if (this.workspace === void 0) {
@@ -22524,6 +22409,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}`,
@@ -22531,6 +22417,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;
@@ -22553,13 +22452,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;
@@ -22608,26 +22516,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);
   }
@@ -22651,8 +22612,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 {
@@ -22791,6 +22773,6 @@ function createOpensteerSemanticRuntime(input = {}) {
   });
 }
 
-export { CloudSessionProxy, DEFERRED_MATCH_ATTR_KEYS, ElementPathError, FlowRecorderCollector, MATCH_ATTRIBUTE_PRIORITY, OPENSTEER_DOM_ACTION_BRIDGE_SYMBOL, OpensteerCloudClient, STABLE_PRIMARY_ATTR_KEYS, assertProviderSupportsEngine, buildArrayFieldPathCandidates, buildDomDescriptorKey, buildDomDescriptorPayload, buildDomDescriptorVersion, buildPathCandidates, buildPathSelectorHint, buildSegmentSelector, cloneElementPath, cloneReplayElementPath, cloneStructuralElementAnchor, createDomDescriptorStore, createDomRuntime, createOpensteerExtractionDescriptorStore, createOpensteerSemanticRuntime, defaultFallbackPolicy, defaultPolicy, defaultRetryPolicy, defaultSettlePolicy, defaultTimeoutPolicy, delayWithSignal, dispatchSemanticOperation, generateReplayScript, hashDomDescriptorPersist, isCurrentUrlField, isValidCssAttributeKey, loadEnvironment, normalizeExtractedValue, normalizeOpensteerProviderMode, parseDomDescriptorRecord, parseExtractionDescriptorRecord, requireCloudAppBaseUrl, resolveCloudConfig, resolveDomActionBridge, resolveExtractedValueInContext, resolveOpensteerEnvironment, resolveOpensteerProvider, resolveOpensteerRuntimeConfig, runWithPolicyTimeout, sanitizeElementPath, sanitizeReplayElementPath, sanitizeStructuralElementAnchor, settleWithPolicy, shouldKeepAttributeForPath };
-//# sourceMappingURL=chunk-7LQL5YUR.js.map
-//# sourceMappingURL=chunk-7LQL5YUR.js.map
+export { CloudSessionProxy, DEFERRED_MATCH_ATTR_KEYS, ElementPathError, FlowRecorderCollector, MATCH_ATTRIBUTE_PRIORITY, OPENSTEER_DOM_ACTION_BRIDGE_SYMBOL, OpensteerCloudClient, STABLE_PRIMARY_ATTR_KEYS, assertProviderSupportsEngine, buildArrayFieldPathCandidates, buildDomDescriptorKey, buildDomDescriptorPayload, buildDomDescriptorVersion, buildPathCandidates, buildPathSelectorHint, buildSegmentSelector, cloneElementPath, cloneReplayElementPath, cloneStructuralElementAnchor, createDomDescriptorStore, createDomRuntime, createOpensteerExtractionDescriptorStore, createOpensteerSemanticRuntime, defaultFallbackPolicy, defaultPolicy, defaultRetryPolicy, defaultSettlePolicy, defaultTimeoutPolicy, delayWithSignal, dispatchSemanticOperation, generateReplayScript, hashDomDescriptorPersist, isBrowserCoreError, isCurrentUrlField, isValidCssAttributeKey, loadEnvironment, normalizeExtractedValue, normalizeOpensteerProviderMode, parseDomDescriptorRecord, parseExtractionDescriptorRecord, requireCloudAppBaseUrl, resolveCloudConfig, resolveDomActionBridge, resolveExtractedValueInContext, resolveOpensteerEnvironment, resolveOpensteerProvider, resolveOpensteerRuntimeConfig, runWithPolicyTimeout, sanitizeElementPath, sanitizeReplayElementPath, sanitizeStructuralElementAnchor, settleWithPolicy, shouldKeepAttributeForPath };
+//# sourceMappingURL=chunk-BVRIPCWA.js.map
+//# sourceMappingURL=chunk-BVRIPCWA.js.map