opensteer 0.9.7 → 0.9.8

package/dist/cli/bin.cjs

@@ -2940,6 +2940,9 @@ var init_metadata2 = __esm({
       {
         pageRef: pageRefSchema,
         sessionRef: sessionRefSchema,
+        targetId: stringSchema({
+          description: "Underlying browser target identifier when available."
+        }),
         openerPageRef: pageRefSchema,
         url: stringSchema({
           description: "Current main-frame URL."
@@ -9143,6 +9146,9 @@ var init_observations = __esm({
         this.store = store;
         this.sessionId = sessionId;
       }
+      configure(input) {
+        return this.store.configureSession(this.sessionId, input);
+      }
       append(input) {
         return this.store.appendEvent(this.sessionId, input);
       }
@@ -9173,40 +9179,14 @@ var init_observations = __esm({
         const sessionId = normalizeNonEmptyString("sessionId", input.sessionId);
         const openedAt = normalizeTimestamp("openedAt", input.openedAt ?? Date.now());
         const config = normalizeObservabilityConfig(input.config);
-        const redactor = createObservationRedactor(config);
-        this.redactors.set(sessionId, redactor);
-        const redactedLabels = redactor.redactLabels(config.labels);
-        const redactedTraceContext = redactor.redactTraceContext(config.traceContext);
-        await withFilesystemLock(this.sessionLockPath(sessionId), async () => {
-          const existing = await this.reconcileSessionManifest(sessionId);
-          if (existing === void 0) {
-            await ensureDirectory(this.sessionEventsDirectory(sessionId));
-            await ensureDirectory(this.sessionArtifactsDirectory(sessionId));
-            const session = {
-              sessionId,
-              profile: config.profile,
-              ...redactedLabels === void 0 ? {} : { labels: redactedLabels },
-              ...redactedTraceContext === void 0 ? {} : { traceContext: redactedTraceContext },
-              openedAt,
-              updatedAt: openedAt,
-              currentSequence: 0,
-              eventCount: 0,
-              artifactCount: 0
-            };
-            await writeJsonFileExclusive(this.sessionManifestPath(sessionId), session);
-            return;
-          }
-          const patched = {
-            ...existing,
-            profile: config.profile,
-            ...redactedLabels === void 0 ? {} : { labels: redactedLabels },
-            ...redactedTraceContext === void 0 ? {} : { traceContext: redactedTraceContext },
-            updatedAt: Math.max(existing.updatedAt, openedAt)
-          };
-          await writeJsonFileAtomic(this.sessionManifestPath(sessionId), patched);
-        });
+        await this.applySessionConfiguration(sessionId, config, openedAt);
         return new FilesystemSessionSink(this, sessionId);
       }
+      async configureSession(sessionId, input) {
+        const updatedAt = normalizeTimestamp("updatedAt", input.updatedAt ?? Date.now());
+        const config = normalizeObservabilityConfig(input.config);
+        await this.applySessionConfiguration(sessionId, config, updatedAt);
+      }
       async getSession(sessionId) {
         const manifestPath = this.sessionManifestPath(sessionId);
         if (!await pathExists(manifestPath)) {
@@ -9427,6 +9407,40 @@ var init_observations = __esm({
       sessionLockPath(sessionId) {
         return path10__default.default.join(this.sessionDirectory(sessionId), ".lock");
       }
+      async applySessionConfiguration(sessionId, config, timestamp) {
+        const redactor = createObservationRedactor(config);
+        this.redactors.set(sessionId, redactor);
+        const redactedLabels = redactor.redactLabels(config.labels);
+        const redactedTraceContext = redactor.redactTraceContext(config.traceContext);
+        await withFilesystemLock(this.sessionLockPath(sessionId), async () => {
+          const existing = await this.reconcileSessionManifest(sessionId);
+          if (existing === void 0) {
+            await ensureDirectory(this.sessionEventsDirectory(sessionId));
+            await ensureDirectory(this.sessionArtifactsDirectory(sessionId));
+            const session = {
+              sessionId,
+              profile: config.profile,
+              ...redactedLabels === void 0 ? {} : { labels: redactedLabels },
+              ...redactedTraceContext === void 0 ? {} : { traceContext: redactedTraceContext },
+              openedAt: timestamp,
+              updatedAt: timestamp,
+              currentSequence: 0,
+              eventCount: 0,
+              artifactCount: 0
+            };
+            await writeJsonFileExclusive(this.sessionManifestPath(sessionId), session);
+            return;
+          }
+          const patched = {
+            ...existing,
+            profile: config.profile,
+            ...redactedLabels === void 0 ? {} : { labels: redactedLabels },
+            ...redactedTraceContext === void 0 ? {} : { traceContext: redactedTraceContext },
+            updatedAt: Math.max(existing.updatedAt, timestamp)
+          };
+          await writeJsonFileAtomic(this.sessionManifestPath(sessionId), patched);
+        });
+      }
       async reconcileSessionManifest(sessionId) {
         const session = await this.getSession(sessionId);
         if (session === void 0) {
@@ -9863,10 +9877,10 @@ async function isAttachedLocalBrowserSessionReachable(record) {
   }
 }
 function isPersistedCloudSessionRecord(value) {
-  return value.layout === OPENSTEER_LIVE_SESSION_LAYOUT && value.version === OPENSTEER_LIVE_SESSION_VERSION && value.provider === "cloud" && typeof value.sessionId === "string" && value.sessionId.length > 0 && typeof value.startedAt === "number" && Number.isFinite(value.startedAt) && typeof value.updatedAt === "number" && Number.isFinite(value.updatedAt);
+  return value.layout === OPENSTEER_LIVE_SESSION_LAYOUT && value.version === OPENSTEER_LIVE_SESSION_VERSION && value.provider === "cloud" && typeof value.sessionId === "string" && value.sessionId.length > 0 && (value.activePageUrl === void 0 || typeof value.activePageUrl === "string") && (value.activePageTitle === void 0 || typeof value.activePageTitle === "string") && typeof value.startedAt === "number" && Number.isFinite(value.startedAt) && typeof value.updatedAt === "number" && Number.isFinite(value.updatedAt);
 }
 function isPersistedLocalBrowserSessionRecord(value) {
-  return value.layout === OPENSTEER_LIVE_SESSION_LAYOUT && value.version === OPENSTEER_LIVE_SESSION_VERSION && value.provider === "local" && (value.engine === "playwright" || value.engine === "abp") && (value.ownership === void 0 || value.ownership === "owned" || value.ownership === "attached") && typeof value.pid === "number" && Number.isFinite(value.pid) && typeof value.startedAt === "number" && Number.isFinite(value.startedAt) && typeof value.updatedAt === "number" && Number.isFinite(value.updatedAt) && typeof value.userDataDir === "string" && value.userDataDir.length > 0;
+  return value.layout === OPENSTEER_LIVE_SESSION_LAYOUT && value.version === OPENSTEER_LIVE_SESSION_VERSION && value.provider === "local" && (value.engine === "playwright" || value.engine === "abp") && (value.ownership === void 0 || value.ownership === "owned" || value.ownership === "attached") && (value.activePageUrl === void 0 || typeof value.activePageUrl === "string") && (value.activePageTitle === void 0 || typeof value.activePageTitle === "string") && typeof value.pid === "number" && Number.isFinite(value.pid) && typeof value.startedAt === "number" && Number.isFinite(value.startedAt) && typeof value.updatedAt === "number" && Number.isFinite(value.updatedAt) && typeof value.userDataDir === "string" && value.userDataDir.length > 0;
 }
 var OPENSTEER_LIVE_SESSION_LAYOUT, OPENSTEER_LIVE_SESSION_VERSION;
 var init_live_session = __esm({
@@ -12145,11 +12159,11 @@ function delay2(ms) {
 function wrapCloudFetchError(error, input) {
   if (!(error instanceof Error)) {
     return new Error(
-      `Failed to reach Opensteer cloud endpoint ${input.method} ${input.url}. Check OPENSTEER_BASE_URL and network reachability from this environment.`
+      `Failed to reach Opensteer cloud endpoint ${input.method} ${input.url}. Check the configured Opensteer cloud base URL and network reachability from this environment.`
     );
   }
   const wrapped = new Error(
-    `Failed to reach Opensteer cloud endpoint ${input.method} ${input.url}. Check OPENSTEER_BASE_URL and network reachability from this environment.`,
+    `Failed to reach Opensteer cloud endpoint ${input.method} ${input.url}. Check the configured Opensteer cloud base URL and network reachability from this environment.`,
     {
       cause: error
     }
@@ -12424,34 +12438,40 @@ function resolveCloudConfig(input = {}) {
     return void 0;
   }
   const cloudProvider = input.provider?.mode === "cloud" ? input.provider : void 0;
-  const apiKey = cloudProvider?.apiKey ?? input.environment?.OPENSTEER_API_KEY;
-  if (!apiKey || apiKey.trim().length === 0) {
+  const apiKey = normalizeOptionalCloudConfigValue(cloudProvider?.apiKey) ?? normalizeOptionalCloudConfigValue(input.environment?.OPENSTEER_API_KEY);
+  if (apiKey === void 0) {
     throw new Error("provider=cloud requires OPENSTEER_API_KEY or provider.apiKey.");
   }
-  const baseUrl = cloudProvider?.baseUrl ?? input.environment?.OPENSTEER_BASE_URL;
-  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;
+  const baseUrl = normalizeOptionalCloudConfigValue(cloudProvider?.baseUrl) ?? normalizeOptionalCloudConfigValue(input.environment?.OPENSTEER_BASE_URL) ?? DEFAULT_OPENSTEER_CLOUD_BASE_URL;
+  const appBaseUrl = normalizeOptionalCloudConfigValue(cloudProvider?.appBaseUrl) ?? normalizeOptionalCloudConfigValue(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(/\/+$/, "") },
+    apiKey,
+    baseUrl,
+    ...appBaseUrl === void 0 ? {} : { appBaseUrl },
     ...cloudProvider?.browserProfile === void 0 ? {} : { browserProfile: cloudProvider.browserProfile }
   };
 }
 function requireCloudAppBaseUrl(cloudConfig) {
-  const appBaseUrl = cloudConfig.appBaseUrl;
-  if (!appBaseUrl || appBaseUrl.trim().length === 0) {
+  const appBaseUrl = normalizeOptionalCloudConfigValue(cloudConfig.appBaseUrl);
+  if (appBaseUrl === void 0) {
     throw new Error(
       'record with provider=cloud requires OPENSTEER_CLOUD_APP_BASE_URL or "--cloud-app-base-url".'
     );
   }
-  return appBaseUrl.trim().replace(/\/+$/, "");
+  return appBaseUrl;
+}
+function normalizeOptionalCloudConfigValue(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const normalized = value.trim().replace(/\/+$/, "");
+  return normalized.length === 0 ? void 0 : normalized;
 }
+var DEFAULT_OPENSTEER_CLOUD_BASE_URL;
 var init_config2 = __esm({
   "src/cloud/config.ts"() {
     init_config();
+    DEFAULT_OPENSTEER_CLOUD_BASE_URL = "https://api.opensteer.com";
   }
 });
 
@@ -12461,7 +12481,7 @@ var init_package = __esm({
   "../runtime-core/package.json"() {
     package_default2 = {
       name: "@opensteer/runtime-core",
-      version: "0.2.6",
+      version: "0.2.7",
       description: "Shared semantic runtime for Opensteer local and cloud execution.",
       license: "MIT",
       type: "module",
@@ -13332,7 +13352,9 @@ function resolveExtractedValueInContext(normalizedValue, options) {
 function stripPositionClauses(nodes) {
   return (nodes || []).map((node) => ({
     ...node,
-    match: (node.match || []).filter((clause) => clause.kind !== "position" && clause.kind !== "text")
+    match: (node.match || []).filter(
+      (clause) => clause.kind !== "position" && clause.kind !== "text"
+    )
   }));
 }
 function dedupeSelectors(selectors) {
@@ -15641,7 +15663,9 @@ var init_runtime = __esm({
             `Unable to resolve structural anchor "${buildPathSelectorHint(anchor)}" in the current session`
           );
         }
-        const replayPath = await this.tryBuildPathFromNode(context.snapshot, target.node, { enableTextMatch: true });
+        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 }
@@ -23269,7 +23293,10 @@ var init_runtime3 = __esm({
       sessionRef;
       pageRef;
       runId;
-      observations;
+      observationSessions = /* @__PURE__ */ new Map();
+      openingObservationSessions = /* @__PURE__ */ new Map();
+      openedObservationSessions = /* @__PURE__ */ new Set();
+      observationSessionStorage = new async_hooks.AsyncLocalStorage();
       operationEventStorage = new async_hooks.AsyncLocalStorage();
       pendingOperationEventCaptures = [];
       ownsEngine = false;
@@ -23321,18 +23348,26 @@ var init_runtime3 = __esm({
       }
       async setObservabilityConfig(input) {
         this.observationConfig = normalizeObservabilityConfig(input);
-        const observationSessionId = this.resolveObservationSessionId();
-        if (observationSessionId === void 0) {
-          return this.observationConfig;
-        }
-        const sink = this.injectedObservationSink ?? (await this.ensureRoot()).observations;
-        this.observations = await sink.openSession({
-          sessionId: observationSessionId,
-          openedAt: Date.now(),
-          config: this.observationConfig
-        });
+        await this.ensureConfiguredObservationSession();
         return this.observationConfig;
       }
+      async withObservationSessionId(sessionId, task) {
+        return await this.observationSessionStorage.run(
+          {
+            mode: "session",
+            sessionId: normalizeNonEmptyString("sessionId", sessionId)
+          },
+          task
+        );
+      }
+      async withoutObservationSession(task) {
+        return await this.observationSessionStorage.run(
+          {
+            mode: "disabled"
+          },
+          task
+        );
+      }
       async open(input = {}, options = {}) {
         assertValidSemanticOperationInput("session.open", input);
         if (input.workspace !== void 0 && normalizeNamespace2(input.workspace) !== this.workspace) {
@@ -26776,7 +26811,7 @@ var init_runtime3 = __esm({
       }
       async resetRuntimeState(options) {
         const engine = this.engine;
-        const observations = this.observations;
+        const observationSessions = [...this.openedObservationSessions];
         this.networkHistory.clear();
         this.sessionRef = void 0;
         this.pageRef = void 0;
@@ -26785,9 +26820,15 @@ var init_runtime3 = __esm({
         this.computer = void 0;
         this.extractionDescriptors = void 0;
         this.engine = void 0;
-        this.observations = void 0;
+        this.observationSessions.clear();
+        this.openingObservationSessions.clear();
+        this.openedObservationSessions.clear();
         this.pendingOperationEventCaptures.length = 0;
-        await observations?.close("runtime_reset").catch(() => void 0);
+        await Promise.allSettled(
+          observationSessions.map(
+            (observationSession) => observationSession.close("runtime_reset").catch(() => void 0)
+          )
+        );
         if (options.disposeEngine && this.ownsEngine && engine?.dispose) {
           await engine.dispose();
         }
@@ -26797,23 +26838,64 @@ var init_runtime3 = __esm({
         if (this.observationConfig.profile === "off") {
           return void 0;
         }
-        if (this.observations !== void 0) {
-          return this.observations;
+        const observationSessionId = this.resolveObservationSessionId();
+        if (observationSessionId === void 0) {
+          return void 0;
+        }
+        const existingObservationSession = this.observationSessions.get(observationSessionId);
+        if (existingObservationSession !== void 0) {
+          return existingObservationSession;
+        }
+        const openingObservationSession = this.openingObservationSessions.get(observationSessionId);
+        if (openingObservationSession !== void 0) {
+          return await openingObservationSession;
+        }
+        const openObservationSessionTask = this.openObservationSession(observationSessionId).finally(
+          () => {
+            this.openingObservationSessions.delete(observationSessionId);
+          }
+        );
+        this.openingObservationSessions.set(observationSessionId, openObservationSessionTask);
+        return await openObservationSessionTask;
+      }
+      async ensureConfiguredObservationSession() {
+        if (this.observationConfig.profile === "off") {
+          return void 0;
         }
         const observationSessionId = this.resolveObservationSessionId();
         if (observationSessionId === void 0) {
           return void 0;
         }
+        const hadObservationSession = this.observationSessions.has(observationSessionId) || this.openingObservationSessions.has(observationSessionId);
+        const observationSession = await this.ensureObservationSession();
+        if (observationSession !== void 0 && hadObservationSession) {
+          await observationSession.configure?.({
+            config: this.observationConfig,
+            updatedAt: Date.now()
+          });
+        }
+        return observationSession;
+      }
+      resolveObservationSessionId() {
+        const scopedSession = this.observationSessionStorage.getStore();
+        if (scopedSession?.mode === "session") {
+          return scopedSession.sessionId;
+        }
+        if (scopedSession?.mode === "disabled") {
+          return void 0;
+        }
+        return this.observationSessionId ?? this.sessionRef;
+      }
+      async openObservationSession(sessionId) {
         const sink = this.injectedObservationSink ?? (await this.ensureRoot()).observations;
-        this.observations = await sink.openSession({
-          sessionId: observationSessionId,
+        const observationSession = await sink.openSession({
+          sessionId,
           openedAt: Date.now(),
           config: this.observationConfig
         });
-        return this.observations;
-      }
-      resolveObservationSessionId() {
-        return this.observationSessionId ?? this.sessionRef;
+        this.observationSessions.set(sessionId, observationSession);
+        this.openedObservationSessions.add(observationSession);
+        return observationSession;
       }
       runWithOperationTimeout(operation, callback, options = {}) {
         const timeoutPolicy = options.timeoutMs === void 0 ? this.policy.timeout : {
@@ -28981,26 +29063,35 @@ function renderOpensteerBootstrap(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")}),`,
+    ...renderCloudBaseUrl(replayTarget),
     ...renderCloudBrowserProfile(replayTarget),
     `  },`,
     `});`
   ];
 }
 function renderRequireEnvHelper(replayTarget) {
-  const baseUrlEnvVar = replayTarget.baseUrlEnvVar ?? "OPENSTEER_BASE_URL";
   const apiKeyEnvVar = replayTarget.apiKeyEnvVar ?? "OPENSTEER_API_KEY";
+  const requiredEnvVars = [
+    ...replayTarget.baseUrlEnvVar === void 0 ? [] : [replayTarget.baseUrlEnvVar],
+    apiKeyEnvVar
+  ];
   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.\`);`,
+    `  throw new Error(\`Missing environment variable \${name}. Set ${requiredEnvVars.join(" and ")} before replaying this recording.\`);`,
     `}`
   ].join("\n");
 }
+function renderCloudBaseUrl(replayTarget) {
+  if (replayTarget.baseUrlEnvVar === void 0) {
+    return [];
+  }
+  return [`    baseUrl: requireEnv(${JSON.stringify(replayTarget.baseUrlEnvVar)}),`];
+}
 function renderCloudBrowserProfile(replayTarget) {
   if (replayTarget.browserProfileId === void 0) {
     return [];
@@ -30263,6 +30354,41 @@ var init_session_proxy = __esm({
     };
   }
 });
+async function persistLocalActivePageHint(runtime, rootPath) {
+  try {
+    await syncPersistedLocalActivePageHint(runtime, rootPath);
+  } catch {
+  }
+}
+async function syncPersistedLocalActivePageHint(runtime, rootPath) {
+  const record = await readPersistedLocalBrowserSessionRecord(rootPath);
+  if (!record) {
+    return;
+  }
+  const sessionInfo = await runtime.info();
+  const activePageRef = sessionInfo.activePageRef;
+  let activePageUrl;
+  let activePageTitle;
+  if (activePageRef !== void 0) {
+    const pages = await runtime.listPages();
+    const activePage = pages.pages.find((page) => page.pageRef === activePageRef);
+    activePageUrl = activePage?.url;
+    activePageTitle = activePage?.title;
+  }
+  const {
+    activePageRef: _previousActivePageRef,
+    activePageUrl: _previousActivePageUrl,
+    activePageTitle: _previousActivePageTitle,
+    ...restRecord
+  } = record;
+  await writePersistedSessionRecord(rootPath, {
+    ...restRecord,
+    updatedAt: Date.now(),
+    ...activePageRef === void 0 ? {} : { activePageRef },
+    ...activePageUrl === void 0 ? {} : { activePageUrl },
+    ...activePageTitle === void 0 ? {} : { activePageTitle }
+  });
+}
 function buildSharedRuntimeOptions(input) {
   const ownership = resolveOwnership(input.browser);
   const engineFactory = input.engineFactory ?? ((factoryOptions) => new OpensteerBrowserManager({
@@ -30309,14 +30435,37 @@ function normalizeWorkspace2(workspace) {
 function resolveOwnership(browser) {
   return typeof browser === "object" && browser.mode === "attach" ? "attached" : "owned";
 }
-var OpensteerRuntime;
+var LocalActivePageHintRuntime, OpensteerRuntime;
 var init_runtime4 = __esm({
   "src/sdk/runtime.ts"() {
     init_src3();
     init_browser_manager();
     init_engine_selection2();
+    init_live_session();
     init_root2();
-    OpensteerRuntime = class extends OpensteerSessionRuntime {
+    LocalActivePageHintRuntime = class extends OpensteerSessionRuntime {
+      async completeWithLocalActivePageHint(operation) {
+        const output = await operation();
+        await persistLocalActivePageHint(this, this.rootPath);
+        return output;
+      }
+      async open(input = {}, options = {}) {
+        return this.completeWithLocalActivePageHint(() => super.open(input, options));
+      }
+      async newPage(input = {}, options = {}) {
+        return this.completeWithLocalActivePageHint(() => super.newPage(input, options));
+      }
+      async activatePage(input, options = {}) {
+        return this.completeWithLocalActivePageHint(() => super.activatePage(input, options));
+      }
+      async closePage(input = {}, options = {}) {
+        return this.completeWithLocalActivePageHint(() => super.closePage(input, options));
+      }
+      async goto(input, options = {}) {
+        return this.completeWithLocalActivePageHint(() => super.goto(input, options));
+      }
+    };
+    OpensteerRuntime = class extends LocalActivePageHintRuntime {
       constructor(options = {}) {
         const publicWorkspace = normalizeWorkspace2(options.workspace);
         const rootPath = options.rootPath ?? (publicWorkspace === void 0 ? path10__default.default.resolve(options.rootDir ?? process.cwd(), ".opensteer", "temporary", crypto.randomUUID()) : resolveFilesystemWorkspacePath({
@@ -31038,7 +31187,7 @@ var init_opensteer = __esm({
 
 // package.json
 var package_default = {
-  version: "0.9.7"};
+  version: "0.9.8"};
 
 // src/cli/bin.ts
 init_browser_manager();
@@ -31693,14 +31842,22 @@ async function buildOperationInput(operation, parsed, runtime) {
       return parsed.rest[0] === void 0 ? {} : { mode: parsed.rest[0] };
     case "page.evaluate":
       if (parsed.rest[0] === void 0) {
-        throw new CliError("missing_arguments", "evaluate requires a script.", CLI_USAGE_HINTS[operation]);
+        throw new CliError(
+          "missing_arguments",
+          "evaluate requires a script.",
+          CLI_USAGE_HINTS[operation]
+        );
       }
       return {
         script: joinRest(parsed.rest, 0)
       };
     case "page.add-init-script":
       if (parsed.rest[0] === void 0) {
-        throw new CliError("missing_arguments", "init-script requires a script.", CLI_USAGE_HINTS[operation]);
+        throw new CliError(
+          "missing_arguments",
+          "init-script requires a script.",
+          CLI_USAGE_HINTS[operation]
+        );
       }
       return {
         script: joinRest(parsed.rest, 0)
@@ -31716,7 +31873,11 @@ async function buildOperationInput(operation, parsed, runtime) {
       return buildElementTargetInput(parsed, "hover");
     case "dom.input": {
       if (parsed.rest[1] === void 0) {
-        throw new CliError("missing_arguments", "input requires an element number and text.", CLI_USAGE_HINTS[operation]);
+        throw new CliError(
+          "missing_arguments",
+          "input requires an element number and text.",
+          CLI_USAGE_HINTS[operation]
+        );
       }
       const pressEnter = readOptionalBoolean(parsed.rawOptions, "press-enter");
       return {
@@ -31747,7 +31908,11 @@ async function buildOperationInput(operation, parsed, runtime) {
     }
     case "dom.extract": {
       if (parsed.rest[0] === void 0) {
-        throw new CliError("missing_arguments", "extract requires a template.", CLI_USAGE_HINTS[operation]);
+        throw new CliError(
+          "missing_arguments",
+          "extract requires a template.",
+          CLI_USAGE_HINTS[operation]
+        );
       }
       const persist = readPersistKey(parsed, "extract");
       return {
@@ -31783,7 +31948,11 @@ async function buildOperationInput(operation, parsed, runtime) {
     }
     case "network.detail": {
       if (parsed.rest[0] === void 0) {
-        throw new CliError("missing_arguments", "network detail requires a record id.", CLI_USAGE_HINTS[operation]);
+        throw new CliError(
+          "missing_arguments",
+          "network detail requires a record id.",
+          CLI_USAGE_HINTS[operation]
+        );
       }
       const probeFlag = readOptionalBoolean(parsed.rawOptions, "probe");
       return {
@@ -31794,7 +31963,11 @@ async function buildOperationInput(operation, parsed, runtime) {
     case "session.fetch": {
       const url = parsed.rest[0];
       if (url === void 0) {
-        throw new CliError("missing_arguments", "fetch requires a URL.", CLI_USAGE_HINTS[operation]);
+        throw new CliError(
+          "missing_arguments",
+          "fetch requires a URL.",
+          CLI_USAGE_HINTS[operation]
+        );
       }
       const bodyJson = readJsonValue(parsed.rawOptions, "body");
       const bodyText = readSingle(parsed.rawOptions, "body-text");
@@ -31833,7 +32006,11 @@ async function buildOperationInput(operation, parsed, runtime) {
       const siteKey = readSingle(parsed.rawOptions, "site-key");
       const pageUrl = readSingle(parsed.rawOptions, "page-url");
       if (provider === void 0 || apiKey === void 0) {
-        throw new CliError("missing_arguments", 'captcha solve requires "--provider" and "--api-key".', CLI_USAGE_HINTS[operation]);
+        throw new CliError(
+          "missing_arguments",
+          'captcha solve requires "--provider" and "--api-key".',
+          CLI_USAGE_HINTS[operation]
+        );
       }
       return {
         provider: readCaptchaProvider(provider),
@@ -31863,7 +32040,11 @@ async function buildOperationInput(operation, parsed, runtime) {
     case "scripts.beautify":
     case "scripts.deobfuscate": {
       if (parsed.rest[0] === void 0) {
-        throw new CliError("missing_arguments", `${parsed.command.join(" ")} requires an artifact id.`, CLI_USAGE_HINTS[operation]);
+        throw new CliError(
+          "missing_arguments",
+          `${parsed.command.join(" ")} requires an artifact id.`,
+          CLI_USAGE_HINTS[operation]
+        );
       }
       const persist = readOptionalBoolean(parsed.rawOptions, "persist");
       return {
@@ -31873,7 +32054,11 @@ async function buildOperationInput(operation, parsed, runtime) {
     }
     case "scripts.sandbox":
       if (parsed.rest[0] === void 0) {
-        throw new CliError("missing_arguments", "scripts sandbox requires an artifact id.", CLI_USAGE_HINTS[operation]);
+        throw new CliError(
+          "missing_arguments",
+          "scripts sandbox requires an artifact id.",
+          CLI_USAGE_HINTS[operation]
+        );
       }
       {
         const fidelity = readSingle(parsed.rawOptions, "fidelity");
@@ -31922,14 +32107,22 @@ async function buildOperationInput(operation, parsed, runtime) {
     case "interaction.get":
     case "interaction.replay":
       if (parsed.rest[0] === void 0) {
-        throw new CliError("missing_arguments", `${parsed.command.join(" ")} requires a trace id.`, CLI_USAGE_HINTS[operation]);
+        throw new CliError(
+          "missing_arguments",
+          `${parsed.command.join(" ")} requires a trace id.`,
+          CLI_USAGE_HINTS[operation]
+        );
       }
       return {
         traceId: parsed.rest[0]
       };
     case "interaction.diff":
       if (parsed.rest[0] === void 0 || parsed.rest[1] === void 0) {
-        throw new CliError("missing_arguments", "interaction diff requires two trace ids.", CLI_USAGE_HINTS[operation]);
+        throw new CliError(
+          "missing_arguments",
+          "interaction diff requires two trace ids.",
+          CLI_USAGE_HINTS[operation]
+        );
       }
       return {
         leftTraceId: parsed.rest[0],
@@ -31937,7 +32130,11 @@ async function buildOperationInput(operation, parsed, runtime) {
       };
     case "artifact.read":
       if (parsed.rest[0] === void 0) {
-        throw new CliError("missing_arguments", "artifact read requires an artifact id.", CLI_USAGE_HINTS[operation]);
+        throw new CliError(
+          "missing_arguments",
+          "artifact read requires an artifact id.",
+          CLI_USAGE_HINTS[operation]
+        );
       }
       return {
         artifactId: parsed.rest[0]
@@ -32075,7 +32272,10 @@ function buildComputerExecuteInput(parsed) {
         }
       };
     default:
-      throw new CliError("unknown_command", `Unknown computer command: ${parsed.command.join(" ")}`);
+      throw new CliError(
+        "unknown_command",
+        `Unknown computer command: ${parsed.command.join(" ")}`
+      );
   }
 }
 async function resolvePageRefByIndex(runtime, index) {
@@ -32105,7 +32305,10 @@ function readRequiredNumber(value, message) {
 }
 function readSingleDirection(value) {
   if (value === void 0 || !SCROLL_DIRECTIONS.has(value)) {
-    throw new CliError("missing_arguments", "scroll requires a direction: up, down, left, or right.");
+    throw new CliError(
+      "missing_arguments",
+      "scroll requires a direction: up, down, left, or right."
+    );
   }
   return value;
 }
@@ -32132,13 +32335,19 @@ function readCaptchaProvider(value) {
 }
 function readCaptchaType(value) {
   if (value === void 0 || !CAPTCHA_TYPES.has(value)) {
-    throw new CliError("invalid_value", 'Expected "--type" to be one of: recaptcha-v2, hcaptcha, turnstile.');
+    throw new CliError(
+      "invalid_value",
+      'Expected "--type" to be one of: recaptcha-v2, hcaptcha, turnstile.'
+    );
   }
   return value;
 }
 function readSandboxFidelity(value) {
   if (value === void 0 || !SANDBOX_FIDELITIES.has(value)) {
-    throw new CliError("invalid_value", 'Expected "--fidelity" to be one of: minimal, standard, full.');
+    throw new CliError(
+      "invalid_value",
+      'Expected "--fidelity" to be one of: minimal, standard, full.'
+    );
   }
   return value;
 }
@@ -32161,7 +32370,10 @@ function readKeyModifiers(value) {
   }
   for (const modifier of modifiers) {
     if (!KEY_MODIFIERS.has(modifier)) {
-      throw new CliError("invalid_value", 'Expected "--modifiers" to contain only: Shift, Control, Alt, Meta.');
+      throw new CliError(
+        "invalid_value",
+        'Expected "--modifiers" to contain only: Shift, Control, Alt, Meta.'
+      );
     }
   }
   return [...new Set(modifiers)];
@@ -33743,6 +33955,172 @@ init_process_owner();
 init_service_state();
 init_service_state();
 
+// src/local-view/browser-target-order.ts
+async function readPageTargetId(page) {
+  const cdp = await page.context().newCDPSession(page);
+  try {
+    const result = await cdp.send("Target.getTargetInfo");
+    const targetId = result?.targetInfo?.targetId;
+    return typeof targetId === "string" && targetId.length > 0 ? targetId : null;
+  } finally {
+    await cdp.detach().catch(() => void 0);
+  }
+}
+async function readBrowserPageTargetOrder(browserContext) {
+  const browser = browserContext.browser();
+  if (!browser || !hasBrowserCdpSession(browser)) {
+    return [];
+  }
+  const cdp = await browser.newBrowserCDPSession();
+  try {
+    const result = await cdp.send("Target.getTargets");
+    return normalizeBrowserPageTargetOrder(result?.targetInfos ?? []);
+  } catch {
+    return [];
+  } finally {
+    await cdp.detach().catch(() => void 0);
+  }
+}
+async function orderPagesByBrowserTargetOrder(browserContext, pages) {
+  if (pages.length < 2) {
+    return pages;
+  }
+  const orderedTargetIds = await readBrowserPageTargetOrder(browserContext);
+  if (orderedTargetIds.length === 0) {
+    return pages;
+  }
+  const rankByTargetId = new Map(orderedTargetIds.map((targetId, index) => [targetId, index]));
+  const targetIds = await Promise.all(
+    pages.map((page) => readPageTargetId(page).catch(() => null))
+  );
+  return pages.map((page, index) => {
+    const targetId = targetIds[index] ?? void 0;
+    return {
+      page,
+      index,
+      rank: targetId === void 0 ? void 0 : rankByTargetId.get(targetId)
+    };
+  }).sort((left, right) => {
+    if (left.rank !== void 0 && right.rank !== void 0) {
+      return left.rank - right.rank;
+    }
+    if (left.rank !== void 0) {
+      return -1;
+    }
+    if (right.rank !== void 0) {
+      return 1;
+    }
+    return left.index - right.index;
+  }).map((entry) => entry.page);
+}
+function hasBrowserCdpSession(browser) {
+  return typeof browser.newBrowserCDPSession === "function";
+}
+function normalizeBrowserPageTargetOrder(targetInfos) {
+  const reversedPageInfos = [];
+  for (const targetInfo of targetInfos) {
+    if (targetInfo.type !== "page") {
+      continue;
+    }
+    const targetId = typeof targetInfo.targetId === "string" && targetInfo.targetId.length > 0 ? targetInfo.targetId : void 0;
+    if (targetId === void 0) {
+      continue;
+    }
+    reversedPageInfos.push({
+      targetId,
+      openerId: typeof targetInfo.openerId === "string" && targetInfo.openerId.length > 0 ? targetInfo.openerId : void 0
+    });
+  }
+  reversedPageInfos.reverse();
+  const rawTargetInfoById = new Map(
+    reversedPageInfos.map((targetInfo) => [targetInfo.targetId, targetInfo])
+  );
+  const targetInfoById = new Map(
+    reversedPageInfos.map(
+      (targetInfo) => [
+        targetInfo.targetId,
+        {
+          ...targetInfo,
+          openerId: resolveAcyclicOpenerId(targetInfo.targetId, rawTargetInfoById)
+        }
+      ]
+    )
+  );
+  const orderedTargetIds = [];
+  const placed = /* @__PURE__ */ new Set();
+  const placeTarget = (targetId) => {
+    if (placed.has(targetId)) {
+      return;
+    }
+    const targetInfo = targetInfoById.get(targetId);
+    if (!targetInfo) {
+      return;
+    }
+    const openerId = targetInfo.openerId;
+    if (openerId === void 0) {
+      orderedTargetIds.push(targetId);
+      placed.add(targetId);
+      return;
+    }
+    placeTarget(openerId);
+    const openerIndex = orderedTargetIds.indexOf(openerId);
+    const insertionIndex = openerIndex === -1 ? orderedTargetIds.length : findPopupInsertionIndex(orderedTargetIds, openerIndex, openerId, targetInfoById);
+    orderedTargetIds.splice(insertionIndex, 0, targetId);
+    placed.add(targetId);
+  };
+  for (const targetInfo of reversedPageInfos) {
+    placeTarget(targetInfo.targetId);
+  }
+  return orderedTargetIds;
+}
+function resolveAcyclicOpenerId(targetId, targetInfoById) {
+  const openerId = targetInfoById.get(targetId)?.openerId;
+  if (openerId === void 0 || !targetInfoById.has(openerId)) {
+    return void 0;
+  }
+  const visitedTargetIds = /* @__PURE__ */ new Set([targetId]);
+  let currentTargetId = openerId;
+  while (currentTargetId !== void 0) {
+    if (visitedTargetIds.has(currentTargetId)) {
+      return void 0;
+    }
+    visitedTargetIds.add(currentTargetId);
+    currentTargetId = targetInfoById.get(currentTargetId)?.openerId;
+  }
+  return openerId;
+}
+function findPopupInsertionIndex(orderedTargetIds, openerIndex, openerTargetId, targetInfoById) {
+  let index = openerIndex + 1;
+  while (index < orderedTargetIds.length) {
+    const candidateTargetId = orderedTargetIds[index];
+    if (!candidateTargetId || !isDescendantTarget(candidateTargetId, openerTargetId, targetInfoById)) {
+      break;
+    }
+    index += 1;
+  }
+  return index;
+}
+function isDescendantTarget(targetId, ancestorTargetId, targetInfoById) {
+  const visitedTargetIds = /* @__PURE__ */ new Set();
+  let currentTargetId = targetId;
+  while (currentTargetId !== void 0) {
+    if (visitedTargetIds.has(currentTargetId)) {
+      return false;
+    }
+    visitedTargetIds.add(currentTargetId);
+    const currentTargetInfo = targetInfoById.get(currentTargetId);
+    const openerId = currentTargetInfo?.openerId;
+    if (openerId === void 0) {
+      return false;
+    }
+    if (openerId === ancestorTargetId) {
+      return true;
+    }
+    currentTargetId = openerId;
+  }
+  return false;
+}
+
 // src/local-view/tab-state-tracker.ts
 var ACTIVATION_INTENT_DISCOVERY_GRACE_MS = 2e3;
 var TabStateTracker = class {
@@ -33758,6 +34136,7 @@ var TabStateTracker = class {
   boundContextCleanup = null;
   constructor(deps) {
     this.deps = deps;
+    this.lastActivePage = deps.initialActivePage ?? null;
   }
   start() {
     if (this.running) {
@@ -33882,7 +34261,7 @@ var TabStateTracker = class {
       this.updatePolling(pages.length);
       const preferredActivePage = this.lastActivePage ?? pages[0] ?? null;
       const pageStates = await Promise.all(
-        pages.map(async (page, index) => {
+        pages.map(async (page, originalIndex) => {
           const metadata = await this.readPageMetadata(page, {
             refresh: args.refreshMetadata
           });
@@ -33892,7 +34271,7 @@ var TabStateTracker = class {
           };
           return {
             page,
-            index,
+            originalIndex,
             targetId: metadata.targetId,
             url: page.url(),
             title: metadata.title,
@@ -33901,17 +34280,18 @@ var TabStateTracker = class {
           };
         })
       );
+      const orderedPageStates = await this.orderPageStates(pageStates);
       const activePage = this.pickActivePage(
-        pageStates,
+        orderedPageStates,
         this.lastActivePage,
         preferredActivePage,
-        this.resolveIntentPage(pageStates)
+        this.resolveIntentPage(orderedPageStates)
       );
       if (activePage && activePage !== this.lastActivePage) {
         this.lastActivePage = activePage;
         this.deps.onActivePageChanged(activePage);
       }
-      const tabs = pageStates.map((state) => ({
+      const tabs = orderedPageStates.map((state) => ({
         index: state.index,
         ...state.targetId === void 0 ? {} : { targetId: state.targetId },
         url: state.url,
@@ -33961,18 +34341,11 @@ var TabStateTracker = class {
     if (cached) {
       return cached;
     }
-    const cdp = await page.context().newCDPSession(page);
-    try {
-      const result = await cdp.send("Target.getTargetInfo");
-      const targetId = result?.targetInfo?.targetId;
-      if (typeof targetId === "string" && targetId.length > 0) {
-        this.targetIdByPage.set(page, targetId);
-        return targetId;
-      }
-      return null;
-    } finally {
-      await cdp.detach().catch(() => void 0);
+    const targetId = await readPageTargetId(page);
+    if (targetId) {
+      this.targetIdByPage.set(page, targetId);
     }
+    return targetId;
   }
   async readFocusState(page) {
     try {
@@ -34040,6 +34413,33 @@ var TabStateTracker = class {
     this.deps.runtimeState.clearPageActivationIntent(this.deps.sessionId, intent.targetId);
     return { page: matched.page };
   }
+  async orderPageStates(pageStates) {
+    if (pageStates.length < 2) {
+      return pageStates.map(({ originalIndex: _originalIndex, ...state }, index) => ({
+        ...state,
+        index
+      }));
+    }
+    const orderedTargetIds = await readBrowserPageTargetOrder(this.deps.browserContext);
+    const rankByTargetId = new Map(orderedTargetIds.map((targetId, index) => [targetId, index]));
+    return [...pageStates].sort((left, right) => {
+      const leftRank = left.targetId === void 0 ? void 0 : rankByTargetId.get(left.targetId);
+      const rightRank = right.targetId === void 0 ? void 0 : rankByTargetId.get(right.targetId);
+      if (leftRank !== void 0 && rightRank !== void 0) {
+        return leftRank - rightRank;
+      }
+      if (leftRank !== void 0) {
+        return -1;
+      }
+      if (rightRank !== void 0) {
+        return 1;
+      }
+      return left.originalIndex - right.originalIndex;
+    }).map(({ originalIndex: _originalIndex, ...state }, index) => ({
+      ...state,
+      index
+    }));
+  }
 };
 
 // src/local-view/view-stream-capture-policy.ts
@@ -34403,6 +34803,7 @@ var SessionViewStreamProducer = class {
       sessionId: this.deps.sessionId,
       pollMs: TAB_STATE_POLL_MS,
       runtimeState: this.deps.runtimeState,
+      initialActivePage: session.page,
       onActivePageChanged: (page) => {
         this.activePage = page;
         void this.queueBindToPage(page).catch(() => void 0);
@@ -34501,7 +34902,20 @@ var SessionViewStreamProducer = class {
       if (!context) {
         throw new Error("Connected browser did not expose a Chromium browser context.");
       }
-      const page = context.pages()[0] ?? await context.newPage();
+      const existingPages = context.pages();
+      if (existingPages.length === 0) {
+        const page2 = await context.newPage();
+        return {
+          browser,
+          context,
+          page: page2
+        };
+      }
+      const orderedPages = await orderPagesByBrowserTargetOrder(context, existingPages);
+      const page = await resolvePersistedActivePage(orderedPages, {
+        ...resolved.record.activePageUrl === void 0 ? {} : { activePageUrl: resolved.record.activePageUrl },
+        ...resolved.record.activePageTitle === void 0 ? {} : { activePageTitle: resolved.record.activePageTitle }
+      }) ?? orderedPages[0];
       return {
         browser,
         context,
@@ -34846,6 +35260,28 @@ async function disconnectPlaywrightChromiumBrowser2(browser) {
   const { disconnectPlaywrightChromiumBrowser: disconnect } = await import('@opensteer/engine-playwright');
   await disconnect(browser);
 }
+async function resolvePersistedActivePage(pages, input) {
+  if (pages.length === 0) {
+    return null;
+  }
+  if (input.activePageUrl === void 0 && input.activePageTitle === void 0) {
+    return null;
+  }
+  const matchesByUrl = input.activePageUrl === void 0 ? pages : pages.filter((page) => page.url() === input.activePageUrl);
+  if (matchesByUrl.length === 0) {
+    return null;
+  }
+  if (input.activePageTitle === void 0) {
+    return matchesByUrl[0] ?? null;
+  }
+  for (const page of matchesByUrl) {
+    const title = await page.title().catch(() => "");
+    if (title === input.activePageTitle) {
+      return page;
+    }
+  }
+  return matchesByUrl[0] ?? null;
+}
 
 // src/local-view/server.ts
 var DEFAULT_MAX_FPS = 12;
@@ -35326,7 +35762,10 @@ async function main() {
     throw new CliError("unknown_command", `Unknown command: ${parsed.command.join(" ")}`);
   }
   if (parsed.options.workspace === void 0) {
-    throw new CliError("missing_workspace", 'Stateful commands require "--workspace <id>" or OPENSTEER_WORKSPACE.');
+    throw new CliError(
+      "missing_workspace",
+      'Stateful commands require "--workspace <id>" or OPENSTEER_WORKSPACE.'
+    );
   }
   const { engineName, provider, runtimeProvider } = resolveCliRuntimeSelection(parsed);
   if (operation === "session.close") {
@@ -35373,7 +35812,10 @@ async function main() {
 }
 async function handleExecCommand(parsed) {
   if (parsed.options.workspace === void 0) {
-    throw new CliError("missing_workspace", 'exec requires "--workspace <id>" or OPENSTEER_WORKSPACE.');
+    throw new CliError(
+      "missing_workspace",
+      'exec requires "--workspace <id>" or OPENSTEER_WORKSPACE.'
+    );
   }
   const expression = parsed.rest.join(" ");
   if (!expression) {
@@ -35516,7 +35958,10 @@ async function handleCloseCommand(parsed, engineName, providerMode, runtimeProvi
 }
 async function handleRecordCommandEntry(parsed) {
   if (parsed.options.workspace === void 0) {
-    throw new CliError("missing_workspace", 'record requires "--workspace <id>" or OPENSTEER_WORKSPACE.');
+    throw new CliError(
+      "missing_workspace",
+      'record requires "--workspace <id>" or OPENSTEER_WORKSPACE.'
+    );
   }
   const url = parsed.options.url ?? parsed.rest[0];
   if (url === void 0) {
@@ -35556,7 +36001,10 @@ async function handleRecordCommandEntry(parsed) {
     return;
   }
   if (parsed.options.launch?.headless === true) {
-    throw new CliError("config_conflict", 'record requires a headed browser. Remove "--headless true".');
+    throw new CliError(
+      "config_conflict",
+      'record requires a headed browser. Remove "--headless true".'
+    );
   }
   if (typeof recordBrowser === "object") {
     throw new CliError("config_conflict", 'record does not support browser.mode="attach".');
@@ -35628,7 +36076,10 @@ function resolveCliBootstrapAction(argv) {
 }
 function buildCliBrowserProfile(parsed) {
   if (parsed.options.cloudProfileReuseIfActive === true && parsed.options.cloudProfileId === void 0) {
-    throw new CliError("invalid_option", '"--cloud-profile-reuse-if-active" requires "--cloud-profile-id <id>".');
+    throw new CliError(
+      "invalid_option",
+      '"--cloud-profile-reuse-if-active" requires "--cloud-profile-id <id>".'
+    );
   }
   return parsed.options.cloudProfileId === void 0 ? void 0 : {
     profileId: parsed.options.cloudProfileId,