opensteer 0.8.10 → 0.8.11

package/dist/cli/bin.cjs

@@ -59,7 +59,7 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 
 // package.json
 var package_default = {
-  version: "0.8.9"};
+  version: "0.8.10"};
 util.promisify(child_process.execFile);
 Math.floor(Date.now() - process.uptime() * 1e3);
 ({ ...process.env});
@@ -2283,6 +2283,9 @@ function isBrowserCoreError(value) {
 // ../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;
+
 // ../protocol/src/identity.ts
 var refPrefixes = [
   "session",
@@ -7472,9 +7475,23 @@ var opensteerInspectStorageInputSchema = objectSchema(
     title: "OpensteerInspectStorageInput"
   }
 );
+var opensteerComputerMouseButtonSchema = enumSchema(["left", "middle", "right"], {
+  title: "OpensteerComputerMouseButton"
+});
+var opensteerComputerKeyModifierSchema = enumSchema(
+  ["Shift", "Control", "Alt", "Meta"],
+  {
+    title: "OpensteerComputerKeyModifier"
+  }
+);
 var opensteerDomClickInputSchema = objectSchema(
   {
     target: opensteerTargetInputSchema,
+    button: opensteerComputerMouseButtonSchema,
+    clickCount: integerSchema({ minimum: 1 }),
+    modifiers: arraySchema(opensteerComputerKeyModifierSchema, {
+      uniqueItems: true
+    }),
     persistAsDescription: stringSchema(),
     captureNetwork: stringSchema({ minLength: 1 })
   },
@@ -7574,18 +7591,6 @@ var opensteerSessionCloseOutputSchema = objectSchema(
     required: ["closed"]
   }
 );
-var opensteerComputerMouseButtonSchema = enumSchema(
-  ["left", "middle", "right"],
-  {
-    title: "OpensteerComputerMouseButton"
-  }
-);
-var opensteerComputerKeyModifierSchema = enumSchema(
-  ["Shift", "Control", "Alt", "Meta"],
-  {
-    title: "OpensteerComputerKeyModifier"
-  }
-);
 var opensteerComputerAnnotationSchema = enumSchema(opensteerComputerAnnotationNames, {
   title: "OpensteerComputerAnnotation"
 });
@@ -12126,6 +12131,30 @@ var OpensteerCloudClient = class {
     });
     return await response.json();
   }
+  async getSessionRecording(sessionId) {
+    const response = await this.request(`/v1/sessions/${encodeURIComponent(sessionId)}/recording`, {
+      method: "GET"
+    });
+    return await response.json();
+  }
+  async startSessionRecording(sessionId) {
+    const response = await this.request(
+      `/v1/sessions/${encodeURIComponent(sessionId)}/recording/start`,
+      {
+        method: "POST"
+      }
+    );
+    return await response.json();
+  }
+  async stopSessionRecording(sessionId) {
+    const response = await this.request(
+      `/v1/sessions/${encodeURIComponent(sessionId)}/recording/stop`,
+      {
+        method: "POST"
+      }
+    );
+    return await response.json();
+  }
   async closeSession(sessionId) {
     const response = await this.request(`/v1/sessions/${encodeURIComponent(sessionId)}`, {
       method: "DELETE"
@@ -12316,9 +12345,11 @@ function resolveCloudConfig(input = {}) {
   if (!baseUrl || baseUrl.trim().length === 0) {
     throw new Error("provider=cloud requires OPENSTEER_BASE_URL or provider.baseUrl.");
   }
+  const appBaseUrl = cloudProvider?.appBaseUrl ?? input.environment?.OPENSTEER_CLOUD_APP_BASE_URL;
   return {
     apiKey: apiKey.trim(),
     baseUrl: baseUrl.trim().replace(/\/+$/, ""),
+    ...appBaseUrl === void 0 || appBaseUrl.trim().length === 0 ? {} : { appBaseUrl: appBaseUrl.trim().replace(/\/+$/, "") },
     ...cloudProvider?.browserProfile === void 0 ? {} : { browserProfile: cloudProvider.browserProfile }
   };
 }
@@ -12333,16 +12364,7 @@ var OPENSTEER_RUNTIME_CORE_VERSION = package_default2.version;
 // ../runtime-core/src/action-boundary.ts
 var actionBoundaryDiagnosticsBySignal = /* @__PURE__ */ new WeakMap();
 async function captureActionBoundarySnapshot(engine, pageRef) {
-  const frames = await engine.listFrames({ pageRef });
-  const mainFrame = frames.find((frame) => frame.isMainFrame);
-  if (!mainFrame) {
-    throw new Error(`page ${pageRef} does not expose a main frame`);
-  }
-  return {
-    pageRef,
-    documentRef: mainFrame.documentRef,
-    url: mainFrame.url
-  };
+  return engine.getActionBoundarySnapshot({ pageRef });
 }
 function createActionBoundaryDiagnostics(input) {
   return {
@@ -12459,6 +12481,7 @@ var NAVIGATION_VISUAL_STABILITY_PROFILE = {
   scope: "visible-frames",
   timeoutMs: 7e3
 };
+var NAVIGATION_POST_LOAD_CAPTURE_WINDOW_MS = 1e3;
 var defaultDomActionSettleObserver = {
   async settle(input) {
     if (input.trigger !== "dom-action") {
@@ -12494,6 +12517,13 @@ var defaultNavigationSettleObserver = {
       return false;
     }
     try {
+      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
+      });
       await input.engine.waitForVisualStability({
         pageRef: input.pageRef,
         timeoutMs: effectiveTimeout,
@@ -23274,11 +23304,11 @@ var SandboxClock = class {
   performanceNow() {
     return this.mode === "manual" ? this.manualNow - this.startedAt : (globalThis.performance?.now() ?? 0) - this.performanceStartedAt;
   }
-  setTimeout(callback, delay3 = 0, ...args) {
-    return this.registerTimer(false, callback, delay3, args);
+  setTimeout(callback, delay4 = 0, ...args) {
+    return this.registerTimer(false, callback, delay4, args);
   }
-  setInterval(callback, delay3 = 0, ...args) {
-    return this.registerTimer(true, callback, delay3, args);
+  setInterval(callback, delay4 = 0, ...args) {
+    return this.registerTimer(true, callback, delay4, args);
   }
   clearTimeout(timerId) {
     this.clearTimer(timerId);
@@ -23299,9 +23329,9 @@ var SandboxClock = class {
       this.clearTimer(timerId);
     }
   }
-  registerTimer(repeat, callback, delay3, args) {
+  registerTimer(repeat, callback, delay4, args) {
     const timerId = this.nextTimerId++;
-    const normalizedDelay = Math.max(0, delay3);
+    const normalizedDelay = Math.max(0, delay4);
     const record = {
       callback,
       args,
@@ -24472,6 +24502,9 @@ var OpensteerSessionRuntime = class {
         const result = await this.requireDom().click({
           pageRef,
           target,
+          ...input.button === void 0 ? {} : { button: input.button },
+          ...input.clickCount === void 0 ? {} : { clickCount: input.clickCount },
+          ...input.modifiers === void 0 ? {} : { modifiers: input.modifiers },
           timeout
         });
         return {
@@ -33191,7 +33224,11 @@ function screenshotMediaType(format2) {
 var SINGLE_ATTRIBUTE_PRIORITY = Array.from(
   /* @__PURE__ */ new Set(["data-testid", "data-test", "data-qa", "data-cy", "id", ...STABLE_PRIMARY_ATTR_KEYS])
 );
-var FLOW_RECORDER_INSTALL_SOURCE = String.raw`(() => {
+function createFlowRecorderInstallScript(options = {}) {
+  const normalizedOptions = {
+    showStopButton: options.showStopButton ?? true
+  };
+  return String.raw`(() => {
   const TOP_LEVEL_ONLY = (() => {
     try {
       return window.top === window.self;
@@ -33216,6 +33253,7 @@ var FLOW_RECORDER_INSTALL_SOURCE = String.raw`(() => {
   const volatileLazyLoadingAttrs = new Set(${JSON.stringify([...VOLATILE_LAZY_LOADING_ATTRS])});
   const volatileClassTokens = new Set(${JSON.stringify([...VOLATILE_CLASS_TOKENS])});
   const volatileLazyClassTokens = new Set(${JSON.stringify([...VOLATILE_LAZY_CLASS_TOKENS])});
+  const options = ${JSON.stringify(normalizedOptions)};
 
   const previous = globalScope[recorderKey];
   if (previous && typeof previous.dispose === "function") {
@@ -33226,6 +33264,7 @@ var FLOW_RECORDER_INSTALL_SOURCE = String.raw`(() => {
   const cleanup = [];
   const inputFlushTimers = new Map();
   const pendingInputs = new Map();
+  let historyStateCache = undefined;
   let stopRequested = false;
   let pendingWheel = undefined;
 
@@ -33546,44 +33585,76 @@ var FLOW_RECORDER_INSTALL_SOURCE = String.raw`(() => {
     inputFlushTimers.set(selector, timerId);
   }
 
-  function updateHistoryState(mode, nextUrl) {
-    let state;
-    try {
-      const raw = sessionStorage.getItem(historyStateKey);
-      state = raw ? JSON.parse(raw) : undefined;
-    } catch {
-      state = undefined;
+  function createDefaultHistoryState(currentUrl) {
+    return {
+      entries: [currentUrl],
+      index: 0,
+    };
+  }
+
+  function normalizeHistoryState(state) {
+    if (
+      !state ||
+      !Array.isArray(state.entries) ||
+      !state.entries.every((entry) => typeof entry === "string") ||
+      !Number.isInteger(state.index)
+    ) {
+      return undefined;
     }
-    if (!state || !Array.isArray(state.entries) || typeof state.index !== "number") {
-      state = { entries: [location.href], index: 0 };
+    const entries = state.entries.slice();
+    if (entries.length === 0) {
+      return createDefaultHistoryState(location.href);
     }
+    return {
+      entries,
+      index: Math.min(entries.length - 1, Math.max(0, state.index)),
+    };
+  }
+
+  function writeHistoryState(state) {
+    const normalized = normalizeHistoryState(state) ?? createDefaultHistoryState(location.href);
+    historyStateCache = normalized;
+    try {
+      sessionStorage.setItem(historyStateKey, JSON.stringify(normalized));
+    } catch {}
+    return normalized;
+  }
+
+  function applyHistoryState(state, mode, nextUrl) {
+    const current = normalizeHistoryState(state) ?? createDefaultHistoryState(location.href);
+    const nextState = {
+      entries: current.entries.slice(),
+      index: current.index,
+    };
     if (mode === "replace") {
-      state.entries[state.index] = nextUrl;
+      nextState.entries[nextState.index] = nextUrl;
     } else if (mode === "push") {
-      state.entries = state.entries.slice(0, state.index + 1);
-      state.entries.push(nextUrl);
-      state.index = state.entries.length - 1;
+      nextState.entries = nextState.entries.slice(0, nextState.index + 1);
+      nextState.entries.push(nextUrl);
+      nextState.index = nextState.entries.length - 1;
     } else if (mode === "back") {
-      state.index = Math.max(0, state.index - 1);
+      nextState.index = Math.max(0, nextState.index - 1);
     } else if (mode === "forward") {
-      state.index = Math.min(state.entries.length - 1, state.index + 1);
+      nextState.index = Math.min(nextState.entries.length - 1, nextState.index + 1);
     }
-    try {
-      sessionStorage.setItem(historyStateKey, JSON.stringify(state));
-    } catch {}
-    return state;
+    return nextState;
+  }
+
+  function updateHistoryState(mode, nextUrl) {
+    return writeHistoryState(applyHistoryState(readHistoryState(), mode, nextUrl));
   }
 
   function readHistoryState() {
+    const cached = normalizeHistoryState(historyStateCache);
+    if (cached) {
+      historyStateCache = cached;
+      return cached;
+    }
     try {
       const raw = sessionStorage.getItem(historyStateKey);
-      const parsed = raw ? JSON.parse(raw) : undefined;
-      if (
-        parsed &&
-        Array.isArray(parsed.entries) &&
-        parsed.entries.every((entry) => typeof entry === "string") &&
-        typeof parsed.index === "number"
-      ) {
+      const parsed = normalizeHistoryState(raw ? JSON.parse(raw) : undefined);
+      if (parsed) {
+        historyStateCache = parsed;
         return parsed;
       }
     } catch {}
@@ -33595,28 +33666,30 @@ var FLOW_RECORDER_INSTALL_SOURCE = String.raw`(() => {
     if (!state) {
       return undefined;
     }
+    if (state.entries[state.index] === currentUrl) {
+      return undefined;
+    }
     if (state.entries[state.index - 1] === currentUrl) {
-      updateHistoryState("back", currentUrl);
+      writeHistoryState({
+        entries: state.entries,
+        index: state.index - 1,
+      });
       return "go-back";
     }
     if (state.entries[state.index + 1] === currentUrl) {
-      updateHistoryState("forward", currentUrl);
+      writeHistoryState({
+        entries: state.entries,
+        index: state.index + 1,
+      });
       return "go-forward";
     }
     const existingIndex = state.entries.lastIndexOf(currentUrl);
-    if (existingIndex !== -1) {
-      if (existingIndex < state.index) {
-        while (readHistoryState()?.index > existingIndex) {
-          updateHistoryState("back", currentUrl);
-        }
-        return "go-back";
-      }
-      if (existingIndex > state.index) {
-        while (readHistoryState()?.index < existingIndex) {
-          updateHistoryState("forward", currentUrl);
-        }
-        return "go-forward";
-      }
+    if (existingIndex !== -1 && existingIndex !== state.index) {
+      writeHistoryState({
+        entries: state.entries,
+        index: existingIndex,
+      });
+      return existingIndex < state.index ? "go-back" : "go-forward";
     }
     return undefined;
   }
@@ -33743,10 +33816,6 @@ var FLOW_RECORDER_INSTALL_SOURCE = String.raw`(() => {
       "  outline: 2px solid #2563eb;",
       "  outline-offset: 2px;",
       "}",
-      "button:disabled {",
-      "  cursor: wait;",
-      "  opacity: 0.8;",
-      "}",
     ].join("\n");
     const button = document.createElement("button");
     button.type = "button";
@@ -33979,7 +34048,8 @@ var FLOW_RECORDER_INSTALL_SOURCE = String.raw`(() => {
       });
       return;
     }
-    if (readHistoryState()?.entries[readHistoryState().index] !== currentUrl) {
+    const state = readHistoryState();
+    if (state?.entries[state.index] !== currentUrl) {
       updateHistoryState("push", currentUrl);
       enqueue({
         kind: "navigate",
@@ -34033,10 +34103,13 @@ var FLOW_RECORDER_INSTALL_SOURCE = String.raw`(() => {
     },
   };
 
-  ensureStopButtonMounted();
+  if (options.showStopButton) {
+    ensureStopButtonMounted();
+  }
   onInstall();
 })();`;
-var FLOW_RECORDER_INSTALL_SCRIPT = FLOW_RECORDER_INSTALL_SOURCE;
+}
+var FLOW_RECORDER_INSTALL_SCRIPT = createFlowRecorderInstallScript();
 var FLOW_RECORDER_DRAIN_SCRIPT = String.raw`(() => {
   const recorder = globalThis.__opensteerFlowRecorder;
   if (!recorder || typeof recorder.drain !== "function") {
@@ -34056,6 +34129,7 @@ var FlowRecorderCollector = class {
   runtime;
   pollIntervalMs;
   onAction;
+  installScript;
   pages = /* @__PURE__ */ new Map();
   actions = [];
   nextPageOrdinal = 0;
@@ -34068,10 +34142,11 @@ var FlowRecorderCollector = class {
     this.runtime = runtime;
     this.pollIntervalMs = options.pollIntervalMs ?? 250;
     this.onAction = options.onAction;
+    this.installScript = options.installScript ?? FLOW_RECORDER_INSTALL_SCRIPT;
   }
   async install() {
     await this.runtime.addInitScript({
-      script: FLOW_RECORDER_INSTALL_SCRIPT
+      script: this.installScript
     });
     const { pages } = await this.runtime.listPages();
     for (const page of pages) {
@@ -34080,7 +34155,7 @@ var FlowRecorderCollector = class {
     await Promise.all(
       pages.map(
         (page) => this.runtime.evaluate({
-          script: FLOW_RECORDER_INSTALL_SCRIPT,
+          script: this.installScript,
           pageRef: page.pageRef
         }).catch(() => void 0)
       )
@@ -34112,6 +34187,18 @@ var FlowRecorderCollector = class {
   getActions() {
     return this.actions.slice();
   }
+  getPages() {
+    return [...this.pages.values()].map((page) => ({
+      pageId: page.pageId,
+      pageRef: page.pageRef,
+      ...page.openerPageRef === void 0 ? {} : { openerPageRef: page.openerPageRef },
+      ...page.openerPageId === void 0 ? {} : { openerPageId: page.openerPageId },
+      currentUrl: page.currentUrl
+    })).sort((left, right) => comparePageIds(left.pageId, right.pageId));
+  }
+  getFocusedPageId() {
+    return this.focusedPageId;
+  }
   async waitForStop() {
     if (this.stopDetected) {
       return;
@@ -34208,10 +34295,17 @@ var FlowRecorderCollector = class {
     }
     for (const listedPage of input.listedPages) {
       if (!input.previousPageRefs.has(listedPage.pageRef)) {
-        const created = this.ensureKnownPage(listedPage.pageRef, listedPage.url, listedPage.openerPageRef);
+        const created = this.ensureKnownPage(
+          listedPage.pageRef,
+          listedPage.url,
+          listedPage.openerPageRef
+        );
         actions.push({
           kind: "new-tab",
-          timestamp: Math.max(0, (firstEventTimestampByPage.get(listedPage.pageRef) ?? input.pollTimestamp) - 1),
+          timestamp: Math.max(
+            0,
+            (firstEventTimestampByPage.get(listedPage.pageRef) ?? input.pollTimestamp) - 1
+          ),
           pageId: created.pageId,
           pageUrl: listedPage.url,
           detail: {
@@ -34265,7 +34359,11 @@ var FlowRecorderCollector = class {
           (event) => this.normalizeRawEvent(event, knownPage, evaluatedPage.currentUrl)
         )
       );
-      this.updateKnownPage(evaluatedPage.pageRef, evaluatedPage.currentUrl, evaluatedPage.openerPageRef);
+      this.updateKnownPage(
+        evaluatedPage.pageRef,
+        evaluatedPage.currentUrl,
+        evaluatedPage.openerPageRef
+      );
     }
     const focusedPage = input.evaluatedPages.find((page) => page.focused);
     if (focusedPage !== void 0 && focusedPage.pageId !== this.focusedPageId) {
@@ -34516,6 +34614,14 @@ function actionSortPriority(kind) {
       return 6;
   }
 }
+function comparePageIds(left, right) {
+  const leftMatch = /^page(\d+)$/u.exec(left);
+  const rightMatch = /^page(\d+)$/u.exec(right);
+  if (leftMatch && rightMatch) {
+    return Number(leftMatch[1]) - Number(rightMatch[1]);
+  }
+  return left.localeCompare(right);
+}
 function delay2(ms) {
   return new Promise((resolve4) => setTimeout(resolve4, ms));
 }
@@ -34565,17 +34671,16 @@ var WINDOW_SCROLL_SCRIPT = String.raw`(deltaX, deltaY) => {
   window.scrollBy(Number(deltaX), Number(deltaY));
 }`;
 function generateReplayScript(options) {
-  const pageIds = collectPageIds(options.actions);
-  const initialPageId = pageIds[0] ?? "page0";
+  const replayTarget = resolveReplayTarget(options);
+  const initialPages = orderInitialPages(resolveInitialPages(options));
+  const activeInitialPageId = resolveActiveInitialPageId(options, initialPages);
+  const initialPageId = initialPages[0]?.pageId ?? "page0";
   const lines = [
     `import { Opensteer } from "opensteer";`,
     ``,
-    `const opensteer = new Opensteer({`,
-    `  workspace: ${JSON.stringify(options.workspace)},`,
-    `  browser: "persistent",`,
-    `});`,
+    ...renderOpensteerBootstrap(replayTarget),
     ``,
-    `const ${initialPageId} = (await opensteer.open(${JSON.stringify(options.startUrl)})).pageRef;`,
+    `const ${initialPageId} = (await opensteer.open(${JSON.stringify(initialPages[0]?.initialUrl ?? "")})).pageRef;`,
     `let activePageRef: string | undefined = ${initialPageId};`,
     ``,
     `async function ensureActive(pageRef: string): Promise<void> {`,
@@ -34616,6 +34721,17 @@ function generateReplayScript(options) {
     `try {`
   ];
   const declaredPages = /* @__PURE__ */ new Set([initialPageId]);
+  for (const page of initialPages.slice(1)) {
+    const openerPageId = page.openerPageId !== void 0 && declaredPages.has(page.openerPageId) ? page.openerPageId : void 0;
+    lines.push(
+      `  const ${page.pageId} = (await opensteer.newPage(${renderNewPageInput(openerPageId, page.initialUrl)})).pageRef;`
+    );
+    lines.push(`  activePageRef = ${page.pageId};`);
+    declaredPages.add(page.pageId);
+  }
+  if (activeInitialPageId !== void 0 && activeInitialPageId !== initialPageId) {
+    lines.push(`  await ensureActive(${activeInitialPageId});`);
+  }
   for (let index = 0; index < options.actions.length; index += 1) {
     const action = options.actions[index];
     const pageVar = action.pageId;
@@ -34648,16 +34764,11 @@ function generateReplayScript(options) {
       case "dblclick":
         lines.push(`  await ensureActive(${pageVar});`);
         lines.push(
-          `  await opensteer.click({ selector: ${JSON.stringify(requireSelector(action))} });`
-        );
-        lines.push(
-          `  await opensteer.click({ selector: ${JSON.stringify(requireSelector(action))} });`
+          `  await opensteer.click({ selector: ${JSON.stringify(requireSelector(action))}, clickCount: 2 });`
         );
         break;
       case "keypress":
-        lines.push(
-          `  await dispatchKey(${pageVar}, ${JSON.stringify(action.detail.key)});`
-        );
+        lines.push(`  await dispatchKey(${pageVar}, ${JSON.stringify(action.detail.key)});`);
         break;
       case "scroll": {
         const { direction, amount, isWindowScroll } = normalizeScrollAction(action);
@@ -34685,7 +34796,7 @@ function generateReplayScript(options) {
       case "new-tab": {
         const openerPageVar = action.detail.openerPageId;
         const shouldUseWaitForPage = shouldUsePopupWait(options.actions, index, openerPageVar);
-        const creationLine = shouldUseWaitForPage && openerPageVar !== void 0 ? `  const ${pageVar} = (await opensteer.waitForPage({ openerPageRef: ${openerPageVar}, timeoutMs: 30_000 })).pageRef;` : `  const ${pageVar} = (await opensteer.newPage({${renderNewPageArguments(action.detail.openerPageId, action.detail.initialUrl)}})).pageRef;`;
+        const creationLine = shouldUseWaitForPage && openerPageVar !== void 0 ? `  const ${pageVar} = (await opensteer.waitForPage({ openerPageRef: ${openerPageVar}, timeoutMs: 30_000 })).pageRef;` : `  const ${pageVar} = (await opensteer.newPage(${renderNewPageInput(action.detail.openerPageId, action.detail.initialUrl)})).pageRef;`;
         lines.push(creationLine);
         lines.push(`  activePageRef = ${pageVar};`);
         declaredPages.add(pageVar);
@@ -34718,29 +34829,114 @@ function generateReplayScript(options) {
   return `${lines.join("\n")}
 `;
 }
-function collectPageIds(actions) {
-  const orderedIds = /* @__PURE__ */ new Set(["page0"]);
-  for (const action of actions) {
-    orderedIds.add(action.pageId);
-    if (action.kind === "new-tab" && action.detail.openerPageId !== void 0) {
-      orderedIds.add(action.detail.openerPageId);
-    }
-    if (action.kind === "switch-tab" && action.detail.fromPageId !== void 0) {
-      orderedIds.add(action.detail.fromPageId);
-    }
-    if (action.kind === "switch-tab") {
-      orderedIds.add(action.detail.toPageId);
+function resolveReplayTarget(options) {
+  if (options.replayTarget !== void 0) {
+    return options.replayTarget;
+  }
+  if (options.workspace !== void 0) {
+    return {
+      kind: "local",
+      workspace: options.workspace
+    };
+  }
+  throw new Error("Replay codegen requires either replayTarget or workspace.");
+}
+function resolveInitialPages(options) {
+  if (options.initialPages !== void 0 && options.initialPages.length > 0) {
+    const unique = /* @__PURE__ */ new Set();
+    return options.initialPages.map((page) => {
+      if (unique.has(page.pageId)) {
+        throw new Error(`Duplicate initial page id "${page.pageId}" in recording bootstrap.`);
+      }
+      unique.add(page.pageId);
+      return page;
+    });
+  }
+  const startUrl = options.startUrl;
+  if (startUrl === void 0) {
+    throw new Error("Replay codegen requires startUrl when initialPages is not provided.");
+  }
+  return [
+    {
+      pageId: "page0",
+      initialUrl: startUrl
     }
+  ];
+}
+function resolveActiveInitialPageId(options, initialPages) {
+  if (options.activePageId !== void 0) {
+    return options.activePageId;
   }
-  return [...orderedIds].sort(comparePageIds);
+  return initialPages[0]?.pageId;
 }
-function comparePageIds(left, right) {
-  const leftMatch = /^page(\d+)$/u.exec(left);
-  const rightMatch = /^page(\d+)$/u.exec(right);
-  if (leftMatch && rightMatch) {
-    return Number(leftMatch[1]) - Number(rightMatch[1]);
+function renderOpensteerBootstrap(replayTarget) {
+  if (replayTarget.kind === "local") {
+    return [
+      `const opensteer = new Opensteer({`,
+      `  workspace: ${JSON.stringify(replayTarget.workspace)},`,
+      `  browser: "persistent",`,
+      `});`
+    ];
   }
-  return left.localeCompare(right);
+  return [
+    renderRequireEnvHelper(replayTarget),
+    ``,
+    `const opensteer = new Opensteer({`,
+    `  provider: {`,
+    `    mode: "cloud",`,
+    `    baseUrl: requireEnv(${JSON.stringify(replayTarget.baseUrlEnvVar ?? "OPENSTEER_BASE_URL")}),`,
+    `    apiKey: requireEnv(${JSON.stringify(replayTarget.apiKeyEnvVar ?? "OPENSTEER_API_KEY")}),`,
+    ...renderCloudBrowserProfile(replayTarget),
+    `  },`,
+    `});`
+  ];
+}
+function renderRequireEnvHelper(replayTarget) {
+  const baseUrlEnvVar = replayTarget.baseUrlEnvVar ?? "OPENSTEER_BASE_URL";
+  const apiKeyEnvVar = replayTarget.apiKeyEnvVar ?? "OPENSTEER_API_KEY";
+  return [
+    `function requireEnv(name: string): string {`,
+    `  const value = process.env[name];`,
+    `  if (typeof value === "string" && value.trim().length > 0) {`,
+    `    return value;`,
+    `  }`,
+    `  throw new Error(\`Missing environment variable \${name}. Set ${baseUrlEnvVar} and ${apiKeyEnvVar} before replaying this recording.\`);`,
+    `}`
+  ].join("\n");
+}
+function renderCloudBrowserProfile(replayTarget) {
+  if (replayTarget.browserProfileId === void 0) {
+    return [];
+  }
+  return [
+    `    browserProfile: {`,
+    `      profileId: ${JSON.stringify(replayTarget.browserProfileId)},`,
+    ...replayTarget.reuseBrowserProfileIfActive ? [`      reuseIfActive: true,`] : [],
+    `    },`
+  ];
+}
+function orderInitialPages(initialPages) {
+  const ordered = [];
+  const declared = /* @__PURE__ */ new Set();
+  const remaining = [...initialPages];
+  while (remaining.length > 0) {
+    let advanced = false;
+    for (let index = 0; index < remaining.length; index += 1) {
+      const page = remaining[index];
+      if (page.openerPageId !== void 0 && !declared.has(page.openerPageId)) {
+        continue;
+      }
+      ordered.push(page);
+      declared.add(page.pageId);
+      remaining.splice(index, 1);
+      advanced = true;
+      break;
+    }
+    if (!advanced) {
+      ordered.push(...remaining.splice(0, remaining.length));
+    }
+  }
+  return ordered;
 }
 function requireSelector(action) {
   if (action.selector === void 0) {
@@ -34774,18 +34970,18 @@ function shouldUsePopupWait(actions, newTabIndex, openerPageId) {
   }
   return previousAction.kind === "click" || previousAction.kind === "dblclick" || previousAction.kind === "keypress";
 }
-function renderNewPageArguments(openerPageId, initialUrl) {
+function renderNewPageInput(openerPageId, initialUrl) {
   const argumentsList = [];
   if (openerPageId !== void 0) {
-    argumentsList.push(` openerPageRef: ${openerPageId}`);
+    argumentsList.push(`openerPageRef: ${openerPageId}`);
   }
   if (initialUrl.length > 0 && initialUrl !== "about:blank") {
-    argumentsList.push(` url: ${JSON.stringify(initialUrl)}`);
+    argumentsList.push(`url: ${JSON.stringify(initialUrl)}`);
   }
   if (argumentsList.length === 0) {
-    return ``;
+    return `{}`;
   }
-  return ` ${argumentsList.join(",")}`.trimStart();
+  return `{ ${argumentsList.join(", ")} }`;
 }
 var OpensteerSemanticRestError = class extends Error {
   opensteerError;
@@ -35934,18 +36130,6 @@ function resolveOwnership(browser) {
 }
 
 // src/sdk/runtime-resolution.ts
-var LOCAL_ONLY_RUNTIME_OPTION_KEYS = [
-  "launch",
-  "context",
-  "engine",
-  "engineFactory",
-  "policy",
-  "descriptorStore",
-  "extractionDescriptorStore",
-  "registryOverrides",
-  "observationSessionId",
-  "observationSink"
-];
 function resolveOpensteerRuntimeConfig(input = {}) {
   const environment = input.environment ?? process.env;
   const provider = resolveOpensteerProvider({
@@ -35970,15 +36154,8 @@ function createOpensteerSemanticRuntime(input = {}) {
     ...input.provider === void 0 ? {} : { provider: input.provider },
     ...input.environment === void 0 ? {} : { environment: input.environment }
   });
-  const localOnlyRuntimeOptions = listLocalOnlyRuntimeOptions(runtimeOptions);
-  const providerMode = config.provider.mode === "cloud" && config.provider.source !== "explicit" && localOnlyRuntimeOptions.length > 0 ? "local" : config.provider.mode;
-  if (config.provider.mode === "cloud" && config.provider.source === "explicit" && localOnlyRuntimeOptions.length > 0) {
-    throw new Error(
-      `provider=cloud does not support local runtime options: ${localOnlyRuntimeOptions.join(", ")}.`
-    );
-  }
-  assertProviderSupportsEngine(providerMode, engine);
-  if (providerMode === "cloud") {
+  assertProviderSupportsEngine(config.provider.mode, engine);
+  if (config.provider.mode === "cloud") {
     return new CloudSessionProxy(new OpensteerCloudClient(config.cloud), {
       ...runtimeOptions.rootDir === void 0 ? {} : { rootDir: runtimeOptions.rootDir },
       ...runtimeOptions.rootPath === void 0 ? {} : { rootPath: runtimeOptions.rootPath },
@@ -35992,9 +36169,6 @@ function createOpensteerSemanticRuntime(input = {}) {
     engineName: engine
   });
 }
-function listLocalOnlyRuntimeOptions(runtimeOptions) {
-  return LOCAL_ONLY_RUNTIME_OPTION_KEYS.filter((key) => runtimeOptions[key] !== void 0);
-}
 async function collectOpensteerStatus(input) {
   const output = {
     provider: {
@@ -36202,6 +36376,65 @@ async function runOpensteerRecordCommand(input) {
     }
   }
 }
+async function runOpensteerCloudRecordCommand(input) {
+  const stdout = input.stdout ?? process.stdout;
+  const stderr = input.stderr ?? process.stderr;
+  const outputPath = resolveRecordOutputPath({
+    rootDir: input.rootDir,
+    workspace: input.workspace,
+    ...input.outputPath === void 0 ? {} : { outputPath: input.outputPath }
+  });
+  let cloud;
+  const resolveCloud = () => {
+    cloud ??= new OpensteerCloudClient(input.cloudConfig);
+    return cloud;
+  };
+  const runtime = input.runtime ?? new CloudSessionProxy(resolveCloud(), {
+    rootDir: input.rootDir,
+    workspace: input.workspace
+  });
+  const client = input.client ?? resolveCloud();
+  const sleep5 = input.sleep ?? delay3;
+  let closed = false;
+  try {
+    await runtime.open({
+      url: input.url,
+      ...input.browser === void 0 ? {} : { browser: input.browser },
+      ...input.launch === void 0 ? {} : { launch: input.launch },
+      ...input.context === void 0 ? {} : { context: input.context }
+    });
+    const sessionId = await resolveCloudRecordingSessionId(runtime);
+    const sessionUrl = buildCloudRecordingSessionUrl(input.cloudConfig, sessionId);
+    await client.startSessionRecording(sessionId);
+    stderr.write(
+      `Recording browser actions for workspace "${input.workspace}". Open ${sessionUrl} and click "Stop recording" in the browser session toolbar when you're done.
+`
+    );
+    const completed = await waitForCloudRecordingCompletion({
+      client,
+      sessionId,
+      ...input.pollIntervalMs === void 0 ? {} : { pollIntervalMs: input.pollIntervalMs },
+      sleep: sleep5
+    });
+    if (completed.result === void 0) {
+      throw new Error("Cloud recording completed without a replay script.");
+    }
+    await promises.mkdir(path7__default.default.dirname(outputPath), { recursive: true });
+    await promises.writeFile(outputPath, completed.result.script, "utf8");
+    await runtime.close();
+    closed = true;
+    stdout.write(`${outputPath}
+`);
+    stderr.write(`Cloud browser session: ${sessionUrl}
+`);
+    stderr.write(`Wrote replay script to ${outputPath}
+`);
+  } finally {
+    if (!closed) {
+      await runtime.close().catch(() => void 0);
+    }
+  }
+}
 function resolveRecordOutputPath(input) {
   if (input.outputPath !== void 0) {
     return path7__default.default.resolve(input.rootDir, input.outputPath);
@@ -36236,6 +36469,35 @@ function createRecorderRuntimeAdapter(runtime) {
     }
   };
 }
+function buildCloudRecordingSessionUrl(cloudConfig, sessionId) {
+  const baseUrl = cloudConfig.appBaseUrl;
+  if (!baseUrl || baseUrl.trim().length === 0) {
+    throw new Error(
+      'record with provider=cloud requires OPENSTEER_CLOUD_APP_BASE_URL or "--cloud-app-base-url".'
+    );
+  }
+  return `${baseUrl.replace(/\/+$/, "")}/browsers/${encodeURIComponent(sessionId)}`;
+}
+async function resolveCloudRecordingSessionId(runtime) {
+  const info = await runtime.info();
+  if (typeof info.sessionId !== "string" || info.sessionId.length === 0) {
+    throw new Error("Cloud recording could not resolve the created session id.");
+  }
+  return info.sessionId;
+}
+async function waitForCloudRecordingCompletion(input) {
+  const pollIntervalMs = input.pollIntervalMs ?? 1e3;
+  for (; ; ) {
+    const state = await input.client.getSessionRecording(input.sessionId);
+    if (state.status === "completed") {
+      return state;
+    }
+    if (state.status === "failed") {
+      throw new Error(state.error ?? "Cloud recording failed.");
+    }
+    await input.sleep(pollIntervalMs);
+  }
+}
 function formatRecordedAction(action) {
   const time = new Date(action.timestamp).toISOString().slice(11, 19);
   switch (action.kind) {
@@ -36267,6 +36529,11 @@ function formatRecordedAction(action) {
       return `[${time}] reload ${action.pageId}`;
   }
 }
+function delay3(ms) {
+  return new Promise((resolve4) => {
+    setTimeout(resolve4, ms);
+  });
+}
 
 // src/cli/bin.ts
 var OPERATION_ALIASES = /* @__PURE__ */ new Map([
@@ -36516,22 +36783,39 @@ async function handleRecordCommandEntry(parsed) {
   }
   const provider = resolveCliProvider(parsed);
   assertCloudCliOptionsMatchProvider(parsed, provider.mode);
-  if (provider.mode !== "local") {
-    throw new Error(
-      'record requires provider=local. Set "--provider local" or clear OPENSTEER_PROVIDER.'
-    );
-  }
   const engineName = resolveCliEngineName(parsed);
   if (engineName !== "playwright") {
     throw new Error("record requires engine=playwright.");
   }
-  if (parsed.options.browser !== void 0 && parsed.options.browser !== "persistent") {
-    throw new Error('record only supports "--browser persistent".');
+  const rootDir = process2__default.default.cwd();
+  const recordBrowser = parsed.options.browser;
+  if (provider.mode === "cloud") {
+    if (typeof recordBrowser === "object") {
+      throw new Error('record does not support browser.mode="attach".');
+    }
+    const runtimeProvider = buildCliRuntimeProvider(parsed, provider.mode);
+    const runtimeConfig = resolveOpensteerRuntimeConfig({
+      ...runtimeProvider === void 0 ? {} : { provider: runtimeProvider },
+      environment: process2__default.default.env
+    });
+    await runOpensteerCloudRecordCommand({
+      cloudConfig: runtimeConfig.cloud,
+      workspace: parsed.options.workspace,
+      url,
+      rootDir,
+      ...recordBrowser === void 0 ? {} : { browser: recordBrowser },
+      ...parsed.options.launch === void 0 ? {} : { launch: parsed.options.launch },
+      ...parsed.options.context === void 0 ? {} : { context: parsed.options.context },
+      ...parsed.options.output === void 0 ? {} : { outputPath: parsed.options.output }
+    });
+    return;
   }
   if (parsed.options.launch?.headless === true) {
     throw new Error('record requires a headed browser. Remove "--headless true".');
   }
-  const rootDir = process2__default.default.cwd();
+  if (recordBrowser !== void 0 && recordBrowser !== "persistent") {
+    throw new Error('record only supports "--browser persistent".');
+  }
   const launch = {
     ...parsed.options.launch ?? {},
     headless: false
@@ -36671,6 +36955,7 @@ var CLI_OPTION_SPECS = {
   provider: { kind: "value" },
   "cloud-base-url": { kind: "value" },
   "cloud-api-key": { kind: "value" },
+  "cloud-app-base-url": { kind: "value" },
   "cloud-profile-id": { kind: "value" },
   "cloud-profile-reuse-if-active": { kind: "boolean" },
   json: { kind: "boolean" },
@@ -36800,6 +37085,7 @@ function parseCommandLine(argv) {
   const provider = providerValue === void 0 ? void 0 : normalizeOpensteerProviderMode(providerValue, "--provider");
   const cloudBaseUrl = readSingle(rawOptions, "cloud-base-url");
   const cloudApiKey = readSingle(rawOptions, "cloud-api-key");
+  const cloudAppBaseUrl = readSingle(rawOptions, "cloud-app-base-url");
   const cloudProfileId = readSingle(rawOptions, "cloud-profile-id");
   const cloudProfileReuseIfActive = readOptionalBoolean(
     rawOptions,
@@ -36821,6 +37107,7 @@ function parseCommandLine(argv) {
     ...provider === void 0 ? {} : { provider },
     ...cloudBaseUrl === void 0 ? {} : { cloudBaseUrl },
     ...cloudApiKey === void 0 ? {} : { cloudApiKey },
+    ...cloudAppBaseUrl === void 0 ? {} : { cloudAppBaseUrl },
     ...cloudProfileId === void 0 ? {} : { cloudProfileId },
     ...cloudProfileReuseIfActive === void 0 ? {} : { cloudProfileReuseIfActive },
     ...json === void 0 ? {} : { json },
@@ -36905,7 +37192,7 @@ function buildCliRuntimeProvider(parsed, providerMode) {
     return explicitProvider?.mode === "local" ? explicitProvider : void 0;
   }
   const browserProfile = buildCliBrowserProfile(parsed);
-  const hasCloudOverrides = parsed.options.cloudBaseUrl !== void 0 || parsed.options.cloudApiKey !== void 0 || browserProfile !== void 0;
+  const hasCloudOverrides = parsed.options.cloudBaseUrl !== void 0 || parsed.options.cloudApiKey !== void 0 || parsed.options.cloudAppBaseUrl !== void 0 || browserProfile !== void 0;
   if (!hasCloudOverrides && explicitProvider?.mode !== "cloud") {
     return void 0;
   }
@@ -36913,11 +37200,12 @@ function buildCliRuntimeProvider(parsed, providerMode) {
     mode: "cloud",
     ...parsed.options.cloudBaseUrl === void 0 ? {} : { baseUrl: parsed.options.cloudBaseUrl },
     ...parsed.options.cloudApiKey === void 0 ? {} : { apiKey: parsed.options.cloudApiKey },
+    ...parsed.options.cloudAppBaseUrl === void 0 ? {} : { appBaseUrl: parsed.options.cloudAppBaseUrl },
     ...browserProfile === void 0 ? {} : { browserProfile }
   };
 }
 function assertCloudCliOptionsMatchProvider(parsed, providerMode) {
-  if (providerMode !== "cloud" && (parsed.options.cloudBaseUrl !== void 0 || parsed.options.cloudApiKey !== void 0 || parsed.options.cloudProfileId !== void 0 || parsed.options.cloudProfileReuseIfActive === true)) {
+  if (providerMode !== "cloud" && (parsed.options.cloudBaseUrl !== void 0 || parsed.options.cloudApiKey !== void 0 || parsed.options.cloudAppBaseUrl !== void 0 || parsed.options.cloudProfileId !== void 0 || parsed.options.cloudProfileReuseIfActive === true)) {
     throw new Error(
       'Cloud-specific options require provider=cloud. Set "--provider cloud" or OPENSTEER_PROVIDER=cloud.'
     );
@@ -37059,6 +37347,7 @@ Common options:
   --provider local|cloud
   --cloud-base-url <url>
   --cloud-api-key <key>
+  --cloud-app-base-url <url>
   --cloud-profile-id <id>
   --cloud-profile-reuse-if-active <true|false>
   --json <true|false>