opensteer 0.9.5 → 0.9.6

package/dist/index.cjs

@@ -1037,9 +1037,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;
 
@@ -6845,21 +6842,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 },
@@ -6938,7 +6920,6 @@ var defaultNavigationSettleObserver = {
 };
 Object.freeze(defaultNavigationSettleObserver);
 var DEFAULT_SETTLE_OBSERVERS = Object.freeze([
-  defaultSnapshotSettleObserver,
   defaultDomActionSettleObserver,
   defaultNavigationSettleObserver
 ]);
@@ -7391,6 +7372,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 +7499,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 +8076,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 +8106,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 +8268,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 +8329,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 +8703,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"
@@ -9181,11 +9190,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 +9209,7 @@ var DomActionExecutor = class {
         hitMissingFromSnapshot: !resolved.snapshot.nodes.some(
           (node) => node.nodeRef === hit.nodeRef
         )
-      },
-      true
+      }
     );
   }
   async resolveActionablePointerTarget(session, operation, resolved) {
@@ -9412,7 +9421,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 +9646,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 +9664,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 +9769,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 +9940,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;
     }
@@ -10551,6 +10567,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 +10672,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 +11082,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" });
@@ -13875,7 +13899,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 +13909,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 +13918,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.`
   );
 }
@@ -14994,6 +15021,48 @@ function isOpensteerEnvironmentKey(key) {
   return key.startsWith(OPENSTEER_ENV_PREFIX);
 }
 
+// src/internal/errors.ts
+function normalizeThrownOpensteerError(error, fallbackMessage) {
+  if (isOpensteerProtocolError(error)) {
+    return toOpensteerError(error);
+  }
+  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) {
@@ -15001,7 +15070,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."
     );
   }
@@ -15011,7 +15081,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 +15522,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 +15715,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 +15767,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 +15827,13 @@ function resolveCloudConfig(input = {}) {
 
 // ../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;
 
 // ../runtime-core/src/internal/errors.ts
-function normalizeThrownOpensteerError(error, fallbackMessage) {
+function normalizeThrownOpensteerError2(error, fallbackMessage) {
   if (isOpensteerProtocolError(error)) {
     return toOpensteerError(error);
   }
@@ -24843,7 +24966,7 @@ function toOpensteerResolvedTarget2(target) {
   };
 }
 function normalizeOpensteerError(error) {
-  return normalizeThrownOpensteerError(error, "Unknown Opensteer runtime failure");
+  return normalizeThrownOpensteerError2(error, "Unknown Opensteer runtime failure");
 }
 function observationArtifactKindFromManifest(kind) {
   switch (kind) {
@@ -25543,6 +25666,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 +25680,8 @@ var CloudSessionProxy = class {
   automation;
   workspaceStore;
   syncWorkspaceOnClose = false;
+  liveSessionStateEstablished = false;
+  storedInstrumentation = [];
   constructor(cloud, options = {}) {
     this.cloud = cloud;
     this.workspace = options.workspace;
@@ -25585,15 +25711,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 +25828,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 +25895,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 +25924,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 +25973,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 +25985,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 +25993,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 +26028,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 +26092,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 +26188,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 +26372,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 +26398,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 +26669,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 +26695,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 +26770,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 +26800,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 +26809,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;