@browserbasehq/stagehand 3.0.6-alpha-a8a7c537fba30d8ce1441d9e454616086ae61fae → 3.0.6-alpha-fdbb58ce7ad8e63a4048089d0b548d76b1803782

package/dist/index.js

@@ -26,6 +26,7 @@ var __spreadValues = (a, b) => {
   return a;
 };
 var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 var __objRest = (source, exclude) => {
   var target = {};
   for (var prop in source)
@@ -65,8 +66,45 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __decoratorStart = (base) => {
+  var _a4;
+  return [, , , __create((_a4 = base == null ? void 0 : base[__knownSymbol("metadata")]) != null ? _a4 : null)];
+};
+var __decoratorStrings = ["class", "method", "getter", "setter", "accessor", "field", "value", "get", "set"];
+var __expectFn = (fn) => fn !== void 0 && typeof fn !== "function" ? __typeError("Function expected") : fn;
+var __decoratorContext = (kind, name, done, metadata, fns) => ({ kind: __decoratorStrings[kind], name, metadata, addInitializer: (fn) => done._ ? __typeError("Already initialized") : fns.push(__expectFn(fn || null)) });
+var __decoratorMetadata = (array, target) => __defNormalProp(target, __knownSymbol("metadata"), array[3]);
+var __runInitializers = (array, flags, self2, value) => {
+  for (var i2 = 0, fns = array[flags >> 1], n = fns && fns.length; i2 < n; i2++) flags & 1 ? fns[i2].call(self2) : value = fns[i2].call(self2, value);
+  return value;
+};
+var __decorateElement = (array, flags, name, decorators, target, extra) => {
+  var fn, it, done, ctx, access, k = flags & 7, s2 = !!(flags & 8), p = !!(flags & 16);
+  var j = k > 3 ? array.length + 1 : k ? s2 ? 1 : 2 : 0, key = __decoratorStrings[k + 5];
+  var initializers = k > 3 && (array[j - 1] = []), extraInitializers = array[j] || (array[j] = []);
+  var desc = k && (!p && !s2 && (target = target.prototype), k < 5 && (k > 3 || !p) && __getOwnPropDesc(k < 4 ? target : { get [name]() {
+    return __privateGet(this, extra);
+  }, set [name](x2) {
+    return __privateSet(this, extra, x2);
+  } }, name));
+  k ? p && k < 4 && __name(extra, (k > 2 ? "set " : k > 1 ? "get " : "") + name) : __name(target, name);
+  for (var i2 = decorators.length - 1; i2 >= 0; i2--) {
+    ctx = __decoratorContext(k, name, done = {}, array[3], extraInitializers);
+    if (k) {
+      ctx.static = s2, ctx.private = p, access = ctx.access = { has: p ? (x2) => __privateIn(target, x2) : (x2) => name in x2 };
+      if (k ^ 3) access.get = p ? (x2) => (k ^ 1 ? __privateGet : __privateMethod)(x2, target, k ^ 4 ? extra : desc.get) : (x2) => x2[name];
+      if (k > 2) access.set = p ? (x2, y) => __privateSet(x2, target, y, k ^ 4 ? extra : desc.set) : (x2, y) => x2[name] = y;
+    }
+    it = (0, decorators[i2])(k ? k < 4 ? p ? extra : desc[key] : k > 4 ? void 0 : { get: desc.get, set: desc.set } : target, ctx), done._ = 1;
+    if (k ^ 4 || it === void 0) __expectFn(it) && (k > 4 ? initializers.unshift(it) : k ? p ? extra = it : desc[key] = it : target = it);
+    else if (typeof it !== "object" || it === null) __typeError("Object expected");
+    else __expectFn(fn = it.get) && (desc.get = fn), __expectFn(fn = it.set) && (desc.set = fn), __expectFn(fn = it.init) && initializers.unshift(fn);
+  }
+  return k || __decoratorMetadata(array, target), desc && __defProp(target, name, desc), p ? k ^ 4 ? extra : desc : target;
+};
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateIn = (member, obj) => Object(obj) !== obj ? __typeError('Cannot use the "in" operator on this value') : member.has(obj);
 var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
 var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
 var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
@@ -141,7 +179,7 @@ var __forAwait = (obj, it, method) => (it = obj[__knownSymbol("asyncIterator")])
 var STAGEHAND_VERSION;
 var init_version = __esm({
   "lib/version.ts"() {
-    STAGEHAND_VERSION = "3.0.6-alpha-a8a7c537fba30d8ce1441d9e454616086ae61fae";
+    STAGEHAND_VERSION = "3.0.6-alpha-fdbb58ce7ad8e63a4048089d0b548d76b1803782";
   }
 });
 
@@ -1260,8 +1298,8 @@ function normalizeXPath(x2) {
   if (s2.length > 1 && s2.endsWith("/")) s2 = s2.slice(0, -1);
   return s2;
 }
-function parseXPathToSteps(path7) {
-  const s2 = path7.trim();
+function parseXPathToSteps(path8) {
+  const s2 = path8.trim();
   let i2 = 0;
   const steps = [];
   while (i2 < s2.length) {
@@ -3422,8 +3460,8 @@ var init_frameLocator = __esm({
 });
 
 // lib/v3/understudy/deepLocator.ts
-function parseXPath(path7) {
-  const s2 = path7.trim();
+function parseXPath(path8) {
+  const s2 = path8.trim();
   let i2 = 0;
   const steps = [];
   while (i2 < s2.length) {
@@ -3454,10 +3492,10 @@ function buildXPathFromSteps2(steps) {
 }
 function deepLocatorThroughIframes(page, root, xpathOrSelector) {
   return __async(this, null, function* () {
-    let path7 = xpathOrSelector.trim();
-    if (path7.startsWith("xpath=")) path7 = path7.slice("xpath=".length).trim();
-    if (!path7.startsWith("/")) path7 = "/" + path7;
-    const steps = parseXPath(path7);
+    let path8 = xpathOrSelector.trim();
+    if (path8.startsWith("xpath=")) path8 = path8.slice("xpath=".length).trim();
+    if (!path8.startsWith("/")) path8 = "/" + path8;
+    const steps = parseXPath(path8);
     let fl;
     let buf = [];
     const flushIntoFrameLocator = () => {
@@ -3652,6 +3690,780 @@ var init_deepLocator = __esm({
   }
 });
 
+// lib/v3/flowLogger.ts
+function truncateCdpIds(value) {
+  return value.replace(
+    /([iI]d:?"?)([0-9A-F]{32})(?="?[,})\s]|$)/g,
+    (_, pre, id) => `${pre}${id.slice(0, 4)}\u2026${id.slice(-4)}`
+  );
+}
+function truncateLine(value, maxLen) {
+  const collapsed = value.replace(/\s+/g, " ");
+  if (collapsed.length <= maxLen) return collapsed;
+  const endLen = Math.floor(maxLen * 0.3);
+  const startLen = maxLen - endLen - 1;
+  return `${collapsed.slice(0, startLen)}\u2026${collapsed.slice(-endLen)}`;
+}
+function formatValue(value) {
+  if (typeof value === "string") return `'${value}'`;
+  if (value == null || typeof value !== "object") return String(value);
+  try {
+    return JSON.stringify(value);
+  } catch (e2) {
+    return "[unserializable]";
+  }
+}
+function formatArgs(args) {
+  if (args === void 0) return "";
+  return (Array.isArray(args) ? args : [args]).filter((e2) => e2 !== void 0).map(formatValue).filter((e2) => e2.length > 0).join(", ");
+}
+function formatTag(label, id, icon) {
+  return id ? `[${icon} #${shortId(id)}${label ? " " + label : ""}]` : "\u2911";
+}
+function formatTimestamp() {
+  const d = /* @__PURE__ */ new Date();
+  const pad = (n, w = 2) => String(n).padStart(w, "0");
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${pad(d.getMilliseconds(), 3)}${pad(nonce++ % 100)}`;
+}
+function sanitizeOptions(options) {
+  const sanitize = (obj) => {
+    if (typeof obj !== "object" || obj === null) return obj;
+    if (Array.isArray(obj)) return obj.map(sanitize);
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[key] = SENSITIVE_KEYS.test(key) ? "******" : sanitize(value);
+    }
+    return result;
+  };
+  return sanitize(__spreadValues({}, options));
+}
+function removeQuotes(str) {
+  return str.replace(/([^\\])["']/g, "$1").replace(/^["']|["']$/g, "").trim();
+}
+function prettifyEvent(event) {
+  var _a4, _b, _c, _d2, _e, _f, _g, _h;
+  const parts = [];
+  if (event.category === "AgentTask") {
+    parts.push(formatTag("", event.taskId, "\u{1F170}"));
+  } else if (event.category === "StagehandStep") {
+    parts.push(formatTag("", event.taskId, "\u{1F170}"));
+    parts.push(formatTag(event.stepLabel, event.stepId, "\u{1F182}"));
+  } else if (event.category === "UnderstudyAction") {
+    parts.push(formatTag("", event.taskId, "\u{1F170}"));
+    parts.push(formatTag(event.stepLabel, event.stepId, "\u{1F182}"));
+    parts.push(formatTag(event.actionLabel, event.actionId, "\u{1F184}"));
+  } else if (event.category === "CDP") {
+    parts.push(formatTag("", event.taskId, "\u{1F170}"));
+    parts.push(formatTag(event.stepLabel, event.stepId, "\u{1F182}"));
+    parts.push(formatTag(event.actionLabel, event.actionId, "\u{1F184}"));
+    parts.push(formatTag("CDP", event.targetId, "\u{1F172}"));
+  } else if (event.category === "LLM") {
+    parts.push(formatTag("", event.taskId, "\u{1F170}"));
+    parts.push(formatTag(event.stepLabel, event.stepId, "\u{1F182}"));
+    parts.push(formatTag("LLM", event.requestId, "\u{1F9E0}"));
+  }
+  let details = "";
+  const argsStr = event.params ? formatArgs(event.params) : "";
+  if (event.category === "AgentTask") {
+    if (event.event === "started") {
+      details = `\u25B7 ${event.method}(${argsStr})`;
+    } else if (event.event === "completed") {
+      const m2 = event.metrics;
+      const durationSec = (m2 == null ? void 0 : m2.durationMs) ? (m2.durationMs / 1e3).toFixed(1) : "?";
+      const llmStats = `${(_a4 = m2 == null ? void 0 : m2.llmRequests) != null ? _a4 : 0} LLM calls \uA71B${(_b = m2 == null ? void 0 : m2.inputTokens) != null ? _b : 0} \uA71C${(_c = m2 == null ? void 0 : m2.outputTokens) != null ? _c : 0} tokens`;
+      const cdpStats = `${(_d2 = m2 == null ? void 0 : m2.cdpEvents) != null ? _d2 : 0} CDP msgs`;
+      details = `\u2713 Agent.execute() DONE in ${durationSec}s | ${llmStats} | ${cdpStats}`;
+    }
+  } else if (event.category === "StagehandStep") {
+    if (event.event === "started") {
+      details = `\u25B7 ${event.method}(${argsStr})`;
+    } else if (event.event === "completed") {
+      const durationSec = ((_e = event.metrics) == null ? void 0 : _e.durationMs) ? (event.metrics.durationMs / 1e3).toFixed(2) : "?";
+      details = `\u2713 ${event.stepLabel || "STEP"} completed in ${durationSec}s`;
+    }
+  } else if (event.category === "UnderstudyAction") {
+    if (event.event === "started") {
+      details = `\u25B7 ${event.method}(${argsStr})`;
+    } else if (event.event === "completed") {
+      const durationSec = ((_f = event.metrics) == null ? void 0 : _f.durationMs) ? (event.metrics.durationMs / 1e3).toFixed(2) : "?";
+      details = `\u2713 ${event.actionLabel || "ACTION"} completed in ${durationSec}s`;
+    }
+  } else if (event.category === "CDP") {
+    const icon = event.event === "call" ? "\u23F5" : "\u23F4";
+    details = `${icon} ${event.method}(${argsStr})`;
+  } else if (event.category === "LLM") {
+    if (event.event === "request") {
+      const promptStr = event.prompt ? " " + String(event.prompt) : "";
+      details = `${event.model} \u23F4${promptStr}`;
+    } else if (event.event === "response") {
+      const hasTokens = event.inputTokens !== void 0 || event.outputTokens !== void 0;
+      const tokenStr = hasTokens ? ` \uA71B${(_g = event.inputTokens) != null ? _g : 0} \uA71C${(_h = event.outputTokens) != null ? _h : 0} |` : "";
+      const outputStr = event.output ? " " + String(event.output) : "";
+      details = `${event.model} \u21B3${tokenStr}${outputStr}`;
+    }
+  }
+  if (!details) return null;
+  const fullLine = `${formatTimestamp()} ${parts.join(" ")} ${details}`;
+  const cleaned = removeQuotes(fullLine);
+  const processed = event.category === "CDP" ? truncateCdpIds(cleaned) : cleaned;
+  return truncateLine(processed, MAX_LINE_LENGTH);
+}
+function shouldFilterCdpEvent(event) {
+  var _a4;
+  if (event.category !== "CDP") return false;
+  if (((_a4 = event.method) == null ? void 0 : _a4.endsWith(".enable")) || event.method === "enable")
+    return true;
+  return event.event === "message" && NOISY_CDP_EVENTS.has(event.method);
+}
+function createJsonlStream(ctx) {
+  return new import_node_stream.Writable({
+    objectMode: true,
+    write(chunk, _, cb) {
+      if (ctx.initialized && isWritable(ctx.fileStreams.jsonl)) {
+        ctx.fileStreams.jsonl.write(chunk, cb);
+      } else cb();
+    }
+  });
+}
+function createPrettyStream(ctx, category, streamKey) {
+  return new import_node_stream.Writable({
+    objectMode: true,
+    write(chunk, _, cb) {
+      const stream = ctx.fileStreams[streamKey];
+      if (!ctx.initialized || !isWritable(stream)) return cb();
+      try {
+        const event = JSON.parse(chunk);
+        if (event.category !== category || shouldFilterCdpEvent(event))
+          return cb();
+        const line = prettifyEvent(event);
+        if (line) stream.write(line + "\n", cb);
+        else cb();
+      } catch (e2) {
+        cb();
+      }
+    }
+  });
+}
+function getConfigDir() {
+  return CONFIG_DIR ? import_node_path.default.resolve(CONFIG_DIR) : "";
+}
+function extractFromContent(content, result) {
+  var _a4, _b, _c, _d2;
+  for (const part of content) {
+    const p = part;
+    if (!result.text && p.text) {
+      result.text = p.type === "text" || !p.type ? p.text : void 0;
+    }
+    if (p.type === "image" || p.type === "image_url") {
+      const url = (_a4 = p.image_url) == null ? void 0 : _a4.url;
+      if (url == null ? void 0 : url.startsWith("data:"))
+        result.extras.push(`${dataToKb(url)}kb image`);
+      else if ((_b = p.source) == null ? void 0 : _b.data)
+        result.extras.push(`${dataToKb(p.source.data)}kb image`);
+      else result.extras.push("image");
+    } else if ((_c = p.source) == null ? void 0 : _c.data) {
+      result.extras.push(`${dataToKb(p.source.data)}kb image`);
+    } else if ((_d2 = p.inlineData) == null ? void 0 : _d2.data) {
+      result.extras.push(`${dataToKb(p.inlineData.data)}kb image`);
+    }
+    if (p.type === "tool_result" && Array.isArray(p.content)) {
+      extractFromContent(p.content, result);
+    }
+  }
+}
+function buildPreview(text, extras, maxLen) {
+  if (!text && extras.length === 0) return void 0;
+  let result = text || "";
+  if (maxLen && result.length > maxLen)
+    result = result.slice(0, maxLen) + "...";
+  if (extras.length > 0) {
+    const extrasStr = extras.map((e2) => `+{${e2}}`).join(" ");
+    result = result ? `${result} ${extrasStr}` : extrasStr;
+  }
+  return result || void 0;
+}
+function formatLlmPromptPreview(messages, options) {
+  try {
+    const lastUserMsg = messages.filter((m2) => m2.role === "user").pop();
+    if (!lastUserMsg) return void 0;
+    const result = {
+      text: void 0,
+      extras: []
+    };
+    if (typeof lastUserMsg.content === "string") {
+      result.text = lastUserMsg.content;
+    } else if (Array.isArray(lastUserMsg.content)) {
+      extractFromContent(lastUserMsg.content, result);
+    } else {
+      return void 0;
+    }
+    if (result.text) {
+      result.text = result.text.replace(/^[Ii]nstruction: /, "");
+    }
+    if (options == null ? void 0 : options.hasSchema) result.extras.push("schema");
+    if (options == null ? void 0 : options.toolCount) result.extras.push(`${options.toolCount} tools`);
+    return buildPreview(result.text, result.extras);
+  } catch (e2) {
+    return void 0;
+  }
+}
+function formatCuaPromptPreview(messages, maxLen = 100) {
+  try {
+    const lastMsg = messages.filter((m2) => {
+      const msg = m2;
+      return msg.role === "user" || msg.type === "tool_result";
+    }).pop();
+    if (!lastMsg) return void 0;
+    const result = {
+      text: void 0,
+      extras: []
+    };
+    if (typeof lastMsg.content === "string") {
+      result.text = lastMsg.content;
+    } else if (typeof lastMsg.text === "string") {
+      result.text = lastMsg.text;
+    } else if (Array.isArray(lastMsg.parts)) {
+      extractFromContent(lastMsg.parts, result);
+    } else if (Array.isArray(lastMsg.content)) {
+      extractFromContent(lastMsg.content, result);
+    }
+    return buildPreview(result.text, result.extras, maxLen);
+  } catch (e2) {
+    return void 0;
+  }
+}
+function formatCuaResponsePreview(output, maxLen = 100) {
+  var _a4, _b, _c, _d2;
+  try {
+    const items = (_d2 = (_c = (_b = (_a4 = output == null ? void 0 : output.candidates) == null ? void 0 : _a4[0]) == null ? void 0 : _b.content) == null ? void 0 : _c.parts) != null ? _d2 : Array.isArray(output) ? output : [];
+    const preview = items.map((item) => {
+      var _a5;
+      const i2 = item;
+      if (i2.text) return i2.text.slice(0, 50);
+      if ((_a5 = i2.functionCall) == null ? void 0 : _a5.name) return `fn:${i2.functionCall.name}`;
+      if (i2.type === "tool_use" && i2.name) return `tool_use:${i2.name}`;
+      return i2.type ? `[${i2.type}]` : "[item]";
+    }).join(" ");
+    return preview.slice(0, maxLen);
+  } catch (e2) {
+    return "[error]";
+  }
+}
+function logAction(actionType) {
+  return function(originalMethod) {
+    if (!CONFIG_DIR) {
+      return originalMethod;
+    }
+    return function(...args) {
+      return __async(this, null, function* () {
+        SessionFileLogger.logUnderstudyActionEvent({
+          actionType,
+          args: args.length > 0 ? args : void 0
+        });
+        try {
+          return yield originalMethod.apply(this, args);
+        } finally {
+          SessionFileLogger.logUnderstudyActionCompleted();
+        }
+      });
+    };
+  };
+}
+function logStagehandStep(invocation, label) {
+  return function(originalMethod) {
+    if (!CONFIG_DIR) {
+      return originalMethod;
+    }
+    return function(...args) {
+      return __async(this, null, function* () {
+        SessionFileLogger.logStagehandStepEvent({
+          invocation,
+          args: args.length > 0 ? args : void 0,
+          label
+        });
+        try {
+          return yield originalMethod.apply(this, args);
+        } finally {
+          SessionFileLogger.logStagehandStepCompleted();
+        }
+      });
+    };
+  };
+}
+var import_node_async_hooks2, import_node_fs, import_node_stream, import_uuid, import_node_path, import_pino2, MAX_LINE_LENGTH, CONFIG_DIR, NOISY_CDP_EVENTS, loggerContext, dataToKb, shortId, nonce, SENSITIVE_KEYS, isWritable, SessionFileLogger;
+var init_flowLogger = __esm({
+  "lib/v3/flowLogger.ts"() {
+    import_node_async_hooks2 = require("async_hooks");
+    import_node_fs = __toESM(require("fs"));
+    import_node_stream = require("stream");
+    import_uuid = require("uuid");
+    import_node_path = __toESM(require("path"));
+    import_pino2 = __toESM(require("pino"));
+    MAX_LINE_LENGTH = 160;
+    CONFIG_DIR = process.env.BROWSERBASE_CONFIG_DIR || "";
+    NOISY_CDP_EVENTS = /* @__PURE__ */ new Set([
+      "Target.targetInfoChanged",
+      "Runtime.executionContextCreated",
+      "Runtime.executionContextDestroyed",
+      "Runtime.executionContextsCleared",
+      "Page.lifecycleEvent",
+      "Network.dataReceived",
+      "Network.loadingFinished",
+      "Network.requestWillBeSentExtraInfo",
+      "Network.responseReceivedExtraInfo",
+      "Network.requestWillBeSent",
+      "Network.responseReceived"
+    ]);
+    loggerContext = new import_node_async_hooks2.AsyncLocalStorage();
+    dataToKb = (data) => (data.length * 0.75 / 1024).toFixed(1);
+    shortId = (id) => id ? id.slice(-4) : "-";
+    nonce = 0;
+    SENSITIVE_KEYS = /apikey|api_key|key|secret|token|password|passwd|pwd|credential|auth/i;
+    isWritable = (s2) => !!(s2 && !s2.destroyed && s2.writable);
+    SessionFileLogger = class _SessionFileLogger {
+      /**
+       * Initialize a new logging context. Call this at the start of a session.
+       * If BROWSERBASE_CONFIG_DIR is not set, logging is disabled.
+       */
+      static init(sessionId, v3Options) {
+        const configDir = getConfigDir();
+        if (!configDir) return;
+        const sessionDir = import_node_path.default.join(configDir, "sessions", sessionId);
+        const ctx = {
+          logger: (0, import_pino2.default)({ level: "silent" }),
+          // Placeholder, replaced below
+          metrics: {
+            llmRequests: 0,
+            llmInputTokens: 0,
+            llmOutputTokens: 0,
+            cdpEvents: 0
+          },
+          sessionId,
+          sessionDir,
+          configDir,
+          initPromise: Promise.resolve(),
+          initialized: false,
+          // Span context - mutable, injected into every log via mixin
+          taskId: null,
+          stepId: null,
+          stepLabel: null,
+          actionId: null,
+          actionLabel: null,
+          fileStreams: {
+            agent: null,
+            stagehand: null,
+            understudy: null,
+            cdp: null,
+            llm: null,
+            jsonl: null
+          }
+        };
+        ctx.initPromise = _SessionFileLogger.initAsync(ctx, v3Options);
+        loggerContext.enterWith(ctx);
+      }
+      static initAsync(ctx, v3Options) {
+        return __async(this, null, function* () {
+          try {
+            yield import_node_fs.default.promises.mkdir(ctx.sessionDir, { recursive: true });
+            if (v3Options) {
+              const sanitizedOptions = sanitizeOptions(v3Options);
+              const sessionJsonPath = import_node_path.default.join(ctx.sessionDir, "session.json");
+              yield import_node_fs.default.promises.writeFile(
+                sessionJsonPath,
+                JSON.stringify(sanitizedOptions, null, 2),
+                "utf-8"
+              );
+            }
+            const latestLink = import_node_path.default.join(ctx.configDir, "sessions", "latest");
+            try {
+              try {
+                yield import_node_fs.default.promises.unlink(latestLink);
+              } catch (e2) {
+              }
+              yield import_node_fs.default.promises.symlink(ctx.sessionId, latestLink, "dir");
+            } catch (e2) {
+            }
+            const dir = ctx.sessionDir;
+            ctx.fileStreams.agent = import_node_fs.default.createWriteStream(
+              import_node_path.default.join(dir, "agent_events.log"),
+              { flags: "a" }
+            );
+            ctx.fileStreams.stagehand = import_node_fs.default.createWriteStream(
+              import_node_path.default.join(dir, "stagehand_events.log"),
+              { flags: "a" }
+            );
+            ctx.fileStreams.understudy = import_node_fs.default.createWriteStream(
+              import_node_path.default.join(dir, "understudy_events.log"),
+              { flags: "a" }
+            );
+            ctx.fileStreams.cdp = import_node_fs.default.createWriteStream(
+              import_node_path.default.join(dir, "cdp_events.log"),
+              { flags: "a" }
+            );
+            ctx.fileStreams.llm = import_node_fs.default.createWriteStream(
+              import_node_path.default.join(dir, "llm_events.log"),
+              { flags: "a" }
+            );
+            ctx.fileStreams.jsonl = import_node_fs.default.createWriteStream(
+              import_node_path.default.join(dir, "session_events.jsonl"),
+              { flags: "a" }
+            );
+            ctx.initialized = true;
+            const streams = [
+              { stream: createJsonlStream(ctx) },
+              { stream: createPrettyStream(ctx, "AgentTask", "agent") },
+              { stream: createPrettyStream(ctx, "StagehandStep", "stagehand") },
+              { stream: createPrettyStream(ctx, "UnderstudyAction", "understudy") },
+              { stream: createPrettyStream(ctx, "CDP", "cdp") },
+              { stream: createPrettyStream(ctx, "LLM", "llm") }
+            ];
+            ctx.logger = (0, import_pino2.default)(
+              {
+                level: "info",
+                // Mixin adds eventId and current span context to every log
+                mixin() {
+                  const store = loggerContext.getStore();
+                  return {
+                    eventId: (0, import_uuid.v7)(),
+                    sessionId: store == null ? void 0 : store.sessionId,
+                    taskId: store == null ? void 0 : store.taskId,
+                    stepId: store == null ? void 0 : store.stepId,
+                    stepLabel: store == null ? void 0 : store.stepLabel,
+                    actionId: store == null ? void 0 : store.actionId,
+                    actionLabel: store == null ? void 0 : store.actionLabel
+                  };
+                }
+              },
+              import_pino2.default.multistream(streams)
+            );
+          } catch (e2) {
+          }
+        });
+      }
+      static close() {
+        return __async(this, null, function* () {
+          const ctx = loggerContext.getStore();
+          if (!ctx) return;
+          yield ctx.initPromise;
+          _SessionFileLogger.logAgentTaskCompleted();
+          yield Promise.all(
+            Object.values(ctx.fileStreams).filter(Boolean).map((s2) => new Promise((r2) => s2.end(r2)))
+          ).catch(() => {
+          });
+        });
+      }
+      static get sessionId() {
+        var _a4, _b;
+        return (_b = (_a4 = loggerContext.getStore()) == null ? void 0 : _a4.sessionId) != null ? _b : null;
+      }
+      static get sessionDir() {
+        var _a4, _b;
+        return (_b = (_a4 = loggerContext.getStore()) == null ? void 0 : _a4.sessionDir) != null ? _b : null;
+      }
+      /**
+       * Get the current logger context object.
+       */
+      static getContext() {
+        var _a4;
+        return (_a4 = loggerContext.getStore()) != null ? _a4 : null;
+      }
+      // ===========================================================================
+      // Agent Task Events
+      // ===========================================================================
+      /**
+       * Start a new task and log it.
+       */
+      static logAgentTaskStarted({
+        invocation,
+        args
+      }) {
+        const ctx = loggerContext.getStore();
+        if (!ctx) return;
+        ctx.taskId = (0, import_uuid.v7)();
+        ctx.stepId = null;
+        ctx.stepLabel = null;
+        ctx.actionId = null;
+        ctx.actionLabel = null;
+        ctx.metrics = {
+          taskStartTime: Date.now(),
+          llmRequests: 0,
+          llmInputTokens: 0,
+          llmOutputTokens: 0,
+          cdpEvents: 0
+        };
+        ctx.logger.info({
+          category: "AgentTask",
+          event: "started",
+          method: invocation,
+          params: args
+        });
+      }
+      /**
+       * Log task completion with metrics summary.
+       */
+      static logAgentTaskCompleted(options) {
+        const ctx = loggerContext.getStore();
+        if (!ctx || !ctx.metrics.taskStartTime) return;
+        const durationMs = Date.now() - ctx.metrics.taskStartTime;
+        const event = {
+          category: "AgentTask",
+          event: "completed",
+          method: "Agent.execute",
+          metrics: {
+            durationMs,
+            llmRequests: ctx.metrics.llmRequests,
+            inputTokens: ctx.metrics.llmInputTokens,
+            outputTokens: ctx.metrics.llmOutputTokens,
+            cdpEvents: ctx.metrics.cdpEvents
+          }
+        };
+        if (options == null ? void 0 : options.cacheHit) {
+          event.msg = "CACHE HIT, NO LLM NEEDED";
+        }
+        ctx.logger.info(event);
+        ctx.taskId = null;
+        ctx.stepId = null;
+        ctx.stepLabel = null;
+        ctx.actionId = null;
+        ctx.actionLabel = null;
+        ctx.metrics.taskStartTime = void 0;
+      }
+      // ===========================================================================
+      // Stagehand Step Events
+      // ===========================================================================
+      static logStagehandStepEvent({
+        invocation,
+        args,
+        label
+      }) {
+        const ctx = loggerContext.getStore();
+        if (!ctx) return (0, import_uuid.v7)();
+        ctx.stepId = (0, import_uuid.v7)();
+        ctx.stepLabel = label.toUpperCase();
+        ctx.actionId = null;
+        ctx.actionLabel = null;
+        ctx.metrics.stepStartTime = Date.now();
+        ctx.logger.info({
+          category: "StagehandStep",
+          event: "started",
+          method: invocation,
+          params: args
+        });
+        return ctx.stepId;
+      }
+      static logStagehandStepCompleted() {
+        const ctx = loggerContext.getStore();
+        if (!ctx || !ctx.stepId) return;
+        const durationMs = ctx.metrics.stepStartTime ? Date.now() - ctx.metrics.stepStartTime : 0;
+        ctx.logger.info({
+          category: "StagehandStep",
+          event: "completed",
+          metrics: { durationMs }
+        });
+        ctx.stepId = null;
+        ctx.stepLabel = null;
+        ctx.actionId = null;
+        ctx.actionLabel = null;
+        ctx.metrics.stepStartTime = void 0;
+      }
+      // ===========================================================================
+      // Understudy Action Events
+      // ===========================================================================
+      static logUnderstudyActionEvent({
+        actionType,
+        target,
+        args
+      }) {
+        const ctx = loggerContext.getStore();
+        if (!ctx) return (0, import_uuid.v7)();
+        ctx.actionId = (0, import_uuid.v7)();
+        ctx.actionLabel = actionType.toUpperCase().replace("UNDERSTUDY.", "").replace("PAGE.", "");
+        ctx.metrics.actionStartTime = Date.now();
+        const params = {};
+        if (target) params.target = target;
+        if (args) params.args = args;
+        ctx.logger.info({
+          category: "UnderstudyAction",
+          event: "started",
+          method: actionType,
+          params: Object.keys(params).length > 0 ? params : void 0
+        });
+        return ctx.actionId;
+      }
+      static logUnderstudyActionCompleted() {
+        const ctx = loggerContext.getStore();
+        if (!ctx || !ctx.actionId) return;
+        const durationMs = ctx.metrics.actionStartTime ? Date.now() - ctx.metrics.actionStartTime : 0;
+        ctx.logger.info({
+          category: "UnderstudyAction",
+          event: "completed",
+          metrics: { durationMs }
+        });
+        ctx.actionId = null;
+        ctx.actionLabel = null;
+        ctx.metrics.actionStartTime = void 0;
+      }
+      // ===========================================================================
+      // CDP Events
+      // ===========================================================================
+      static logCdpEvent(eventType, {
+        method,
+        params,
+        targetId
+      }, explicitCtx) {
+        const ctx = explicitCtx != null ? explicitCtx : loggerContext.getStore();
+        if (!ctx) return;
+        if (eventType === "call") ctx.metrics.cdpEvents++;
+        ctx.logger.info({
+          category: "CDP",
+          event: eventType,
+          method,
+          params,
+          targetId
+        });
+      }
+      static logCdpCallEvent(data, ctx) {
+        _SessionFileLogger.logCdpEvent("call", data, ctx);
+      }
+      static logCdpMessageEvent(data, ctx) {
+        _SessionFileLogger.logCdpEvent("message", data, ctx);
+      }
+      // ===========================================================================
+      // LLM Events
+      // ===========================================================================
+      static logLlmRequest({
+        requestId,
+        model,
+        prompt
+      }, explicitCtx) {
+        const ctx = explicitCtx != null ? explicitCtx : loggerContext.getStore();
+        if (!ctx) return;
+        ctx.metrics.llmRequests++;
+        ctx.logger.info({
+          category: "LLM",
+          event: "request",
+          requestId,
+          method: "LLM.request",
+          model,
+          prompt
+        });
+      }
+      static logLlmResponse({
+        requestId,
+        model,
+        output,
+        inputTokens,
+        outputTokens
+      }, explicitCtx) {
+        const ctx = explicitCtx != null ? explicitCtx : loggerContext.getStore();
+        if (!ctx) return;
+        ctx.metrics.llmInputTokens += inputTokens != null ? inputTokens : 0;
+        ctx.metrics.llmOutputTokens += outputTokens != null ? outputTokens : 0;
+        ctx.logger.info({
+          category: "LLM",
+          event: "response",
+          requestId,
+          method: "LLM.response",
+          model,
+          output,
+          inputTokens,
+          outputTokens
+        });
+      }
+      // ===========================================================================
+      // LLM Logging Middleware
+      // ===========================================================================
+      /**
+       * Create middleware for wrapping language models with LLM call logging.
+       * Returns a no-op middleware when logging is disabled.
+       */
+      static createLlmLoggingMiddleware(modelId) {
+        if (!CONFIG_DIR) {
+          return {
+            wrapGenerate: (_0) => __async(null, [_0], function* ({ doGenerate }) {
+              return doGenerate();
+            })
+          };
+        }
+        return {
+          wrapGenerate: (_0) => __async(null, [_0], function* ({ doGenerate, params }) {
+            var _a4, _b, _c, _d2, _e;
+            const ctx = _SessionFileLogger.getContext();
+            if (!ctx) {
+              return doGenerate();
+            }
+            const llmRequestId = (0, import_uuid.v7)();
+            const toolCount = Array.isArray(params.tools) ? params.tools.length : 0;
+            const messages = (_a4 = params.prompt) != null ? _a4 : [];
+            const lastMsg = messages.filter((m2) => m2.role !== "system").pop();
+            const extracted = {
+              text: void 0,
+              extras: []
+            };
+            let rolePrefix = (_b = lastMsg == null ? void 0 : lastMsg.role) != null ? _b : "?";
+            if (lastMsg) {
+              if (typeof lastMsg.content === "string") {
+                extracted.text = lastMsg.content;
+              } else if (Array.isArray(lastMsg.content)) {
+                const toolResult = lastMsg.content.find((p) => p.type === "tool-result");
+                if (toolResult) {
+                  rolePrefix = `tool result: ${toolResult.toolName}()`;
+                  const out = toolResult.output;
+                  if ((out == null ? void 0 : out.type) === "json" && out.value) {
+                    extracted.text = JSON.stringify(out.value).slice(0, 150);
+                  } else if (Array.isArray(out == null ? void 0 : out.value)) {
+                    extractFromContent(out.value, extracted);
+                  }
+                } else {
+                  extractFromContent(lastMsg.content, extracted);
+                }
+              }
+            }
+            const promptText = extracted.text || "(no text)";
+            const promptPreview = `${rolePrefix}: ${promptText} +{${toolCount} tools}`;
+            _SessionFileLogger.logLlmRequest(
+              {
+                requestId: llmRequestId,
+                model: modelId,
+                operation: "generateText",
+                prompt: promptPreview
+              },
+              ctx
+            );
+            const result = yield doGenerate();
+            const res = result;
+            let outputPreview = res.text || "";
+            if (!outputPreview && res.content) {
+              if (typeof res.content === "string") {
+                outputPreview = res.content;
+              } else if (Array.isArray(res.content)) {
+                outputPreview = res.content.map(
+                  (c) => c.text || (c.type === "tool-call" ? `tool call: ${c.toolName}()` : `[${c.type}]`)
+                ).join(" ");
+              }
+            }
+            if (!outputPreview && ((_c = res.toolCalls) == null ? void 0 : _c.length)) {
+              outputPreview = `[${res.toolCalls.length} tool calls]`;
+            }
+            _SessionFileLogger.logLlmResponse(
+              {
+                requestId: llmRequestId,
+                model: modelId,
+                operation: "generateText",
+                output: outputPreview || "[empty]",
+                inputTokens: (_d2 = result.usage) == null ? void 0 : _d2.inputTokens,
+                outputTokens: (_e = result.usage) == null ? void 0 : _e.outputTokens
+              },
+              ctx
+            );
+            return result;
+          })
+        };
+      }
+    };
+  }
+});
+
 // ../../node_modules/.pnpm/escape-string-regexp@4.0.0/node_modules/escape-string-regexp/index.js
 var require_escape_string_regexp = __commonJS({
   "../../node_modules/.pnpm/escape-string-regexp@4.0.0/node_modules/escape-string-regexp/index.js"(exports2, module2) {
@@ -3961,7 +4773,7 @@ var require_common = __commonJS({
 // ../../node_modules/.pnpm/debug@4.4.1/node_modules/debug/src/browser.js
 var require_browser = __commonJS({
   "../../node_modules/.pnpm/debug@4.4.1/node_modules/debug/src/browser.js"(exports2, module2) {
-    exports2.formatArgs = formatArgs;
+    exports2.formatArgs = formatArgs2;
     exports2.save = save;
     exports2.load = load;
     exports2.useColors = useColors;
@@ -4067,7 +4879,7 @@ var require_browser = __commonJS({
       typeof navigator !== "undefined" && navigator.userAgent && (m2 = navigator.userAgent.toLowerCase().match(/firefox\/(\d+)/)) && parseInt(m2[1], 10) >= 31 || // Double check webkit in userAgent just in case we are in a worker
       typeof navigator !== "undefined" && navigator.userAgent && navigator.userAgent.toLowerCase().match(/applewebkit\/(\d+)/);
     }
-    function formatArgs(args) {
+    function formatArgs2(args) {
       args[0] = (this.useColors ? "%c" : "") + this.namespace + (this.useColors ? " %c" : " ") + args[0] + (this.useColors ? "%c " : " ") + "+" + module2.exports.humanize(this.diff);
       if (!this.useColors) {
         return;
@@ -4250,7 +5062,7 @@ var require_node = __commonJS({
     var util = require("util");
     exports2.init = init;
     exports2.log = log;
-    exports2.formatArgs = formatArgs;
+    exports2.formatArgs = formatArgs2;
     exports2.save = save;
     exports2.load = load;
     exports2.useColors = useColors;
@@ -4366,7 +5178,7 @@ var require_node = __commonJS({
     function useColors() {
       return "colors" in exports2.inspectOpts ? Boolean(exports2.inspectOpts.colors) : tty.isatty(process.stderr.fd);
     }
-    function formatArgs(args) {
+    function formatArgs2(args) {
       const { namespace: name, useColors: useColors2 } = this;
       if (useColors2) {
         const c = this.color;
@@ -4432,11 +5244,11 @@ var require_src = __commonJS({
 var require_is_docker = __commonJS({
   "../../node_modules/.pnpm/is-docker@2.2.1/node_modules/is-docker/index.js"(exports2, module2) {
     "use strict";
-    var fs11 = require("fs");
+    var fs12 = require("fs");
     var isDocker;
     function hasDockerEnv() {
       try {
-        fs11.statSync("/.dockerenv");
+        fs12.statSync("/.dockerenv");
         return true;
       } catch (_) {
         return false;
@@ -4444,7 +5256,7 @@ var require_is_docker = __commonJS({
     }
     function hasDockerCGroup() {
       try {
-        return fs11.readFileSync("/proc/self/cgroup", "utf8").includes("docker");
+        return fs12.readFileSync("/proc/self/cgroup", "utf8").includes("docker");
       } catch (_) {
         return false;
       }
@@ -4463,7 +5275,7 @@ var require_is_wsl = __commonJS({
   "../../node_modules/.pnpm/is-wsl@2.2.0/node_modules/is-wsl/index.js"(exports2, module2) {
     "use strict";
     var os3 = require("os");
-    var fs11 = require("fs");
+    var fs12 = require("fs");
     var isDocker = require_is_docker();
     var isWsl3 = () => {
       if (process.platform !== "linux") {
@@ -4476,7 +5288,7 @@ var require_is_wsl = __commonJS({
         return true;
       }
       try {
-        return fs11.readFileSync("/proc/version", "utf8").toLowerCase().includes("microsoft") ? !isDocker() : false;
+        return fs12.readFileSync("/proc/version", "utf8").toLowerCase().includes("microsoft") ? !isDocker() : false;
       } catch (_) {
         return false;
       }
@@ -10393,31 +11205,31 @@ var require_node_domexception = __commonJS({
 });
 
 // ../../node_modules/.pnpm/fetch-blob@3.2.0/node_modules/fetch-blob/from.js
-var import_node_fs, import_node_path, import_node_domexception, stat, blobFromSync, blobFrom, fileFrom, fileFromSync, fromBlob, fromFile, _path, _start, _BlobDataItem, BlobDataItem;
+var import_node_fs2, import_node_path2, import_node_domexception, stat, blobFromSync, blobFrom, fileFrom, fileFromSync, fromBlob, fromFile, _path, _start, _BlobDataItem, BlobDataItem;
 var init_from = __esm({
   "../../node_modules/.pnpm/fetch-blob@3.2.0/node_modules/fetch-blob/from.js"() {
-    import_node_fs = require("fs");
-    import_node_path = require("path");
+    import_node_fs2 = require("fs");
+    import_node_path2 = require("path");
     import_node_domexception = __toESM(require_node_domexception(), 1);
     init_file();
     init_fetch_blob();
-    ({ stat } = import_node_fs.promises);
-    blobFromSync = (path7, type) => fromBlob((0, import_node_fs.statSync)(path7), path7, type);
-    blobFrom = (path7, type) => stat(path7).then((stat2) => fromBlob(stat2, path7, type));
-    fileFrom = (path7, type) => stat(path7).then((stat2) => fromFile(stat2, path7, type));
-    fileFromSync = (path7, type) => fromFile((0, import_node_fs.statSync)(path7), path7, type);
-    fromBlob = (stat2, path7, type = "") => new fetch_blob_default([new BlobDataItem({
-      path: path7,
+    ({ stat } = import_node_fs2.promises);
+    blobFromSync = (path8, type) => fromBlob((0, import_node_fs2.statSync)(path8), path8, type);
+    blobFrom = (path8, type) => stat(path8).then((stat2) => fromBlob(stat2, path8, type));
+    fileFrom = (path8, type) => stat(path8).then((stat2) => fromFile(stat2, path8, type));
+    fileFromSync = (path8, type) => fromFile((0, import_node_fs2.statSync)(path8), path8, type);
+    fromBlob = (stat2, path8, type = "") => new fetch_blob_default([new BlobDataItem({
+      path: path8,
       size: stat2.size,
       lastModified: stat2.mtimeMs,
       start: 0
     })], { type });
-    fromFile = (stat2, path7, type = "") => new file_default([new BlobDataItem({
-      path: path7,
+    fromFile = (stat2, path8, type = "") => new file_default([new BlobDataItem({
+      path: path8,
       size: stat2.size,
       lastModified: stat2.mtimeMs,
       start: 0
-    })], (0, import_node_path.basename)(path7), { type, lastModified: stat2.mtimeMs });
+    })], (0, import_node_path2.basename)(path8), { type, lastModified: stat2.mtimeMs });
     _BlobDataItem = class _BlobDataItem {
       constructor(options) {
         __privateAdd(this, _path);
@@ -10445,7 +11257,7 @@ var init_from = __esm({
           if (mtimeMs > this.lastModified) {
             throw new import_node_domexception.default("The requested file could not be read, typically due to permission problems that have occurred after a reference to a file was acquired.", "NotReadableError");
           }
-          yield* __yieldStar((0, import_node_fs.createReadStream)(__privateGet(this, _path), {
+          yield* __yieldStar((0, import_node_fs2.createReadStream)(__privateGet(this, _path), {
             start: __privateGet(this, _start),
             end: __privateGet(this, _start) + this.size - 1
           }));
@@ -10851,7 +11663,7 @@ function consumeBody(data) {
     if (body === null) {
       return import_node_buffer.Buffer.alloc(0);
     }
-    if (!(body instanceof import_node_stream.default)) {
+    if (!(body instanceof import_node_stream2.default)) {
       return import_node_buffer.Buffer.alloc(0);
     }
     const accum = [];
@@ -10896,10 +11708,10 @@ function consumeBody(data) {
     }
   });
 }
-var import_node_stream, import_node_util, import_node_buffer, pipeline, INTERNALS, Body, clone, getNonSpecFormDataBoundary, extractContentType, getTotalBytes, writeToStream;
+var import_node_stream2, import_node_util, import_node_buffer, pipeline, INTERNALS, Body, clone, getNonSpecFormDataBoundary, extractContentType, getTotalBytes, writeToStream;
 var init_body = __esm({
   "../../node_modules/.pnpm/node-fetch@3.3.2/node_modules/node-fetch/src/body.js"() {
-    import_node_stream = __toESM(require("stream"), 1);
+    import_node_stream2 = __toESM(require("stream"), 1);
     import_node_util = require("util");
     import_node_buffer = require("buffer");
     init_fetch_blob();
@@ -10907,7 +11719,7 @@ var init_body = __esm({
     init_fetch_error();
     init_base();
     init_is();
-    pipeline = (0, import_node_util.promisify)(import_node_stream.default.pipeline);
+    pipeline = (0, import_node_util.promisify)(import_node_stream2.default.pipeline);
     INTERNALS = Symbol("Body internals");
     Body = class {
       constructor(body, {
@@ -10924,7 +11736,7 @@ var init_body = __esm({
           body = import_node_buffer.Buffer.from(body);
         } else if (ArrayBuffer.isView(body)) {
           body = import_node_buffer.Buffer.from(body.buffer, body.byteOffset, body.byteLength);
-        } else if (body instanceof import_node_stream.default) {
+        } else if (body instanceof import_node_stream2.default) {
         } else if (body instanceof FormData2) {
           body = formDataToBlob(body);
           boundary = body.type.split("=")[1];
@@ -10933,9 +11745,9 @@ var init_body = __esm({
         }
         let stream = body;
         if (import_node_buffer.Buffer.isBuffer(body)) {
-          stream = import_node_stream.default.Readable.from(body);
+          stream = import_node_stream2.default.Readable.from(body);
         } else if (isBlob(body)) {
-          stream = import_node_stream.default.Readable.from(body.stream());
+          stream = import_node_stream2.default.Readable.from(body.stream());
         }
         this[INTERNALS] = {
           body,
@@ -10945,7 +11757,7 @@ var init_body = __esm({
           error: null
         };
         this.size = size;
-        if (body instanceof import_node_stream.default) {
+        if (body instanceof import_node_stream2.default) {
           body.on("error", (error_) => {
             const error = error_ instanceof FetchBaseError ? error_ : new FetchError(`Invalid response body while trying to fetch ${this.url}: ${error_.message}`, "system", error_);
             this[INTERNALS].error = error;
@@ -11051,9 +11863,9 @@ var init_body = __esm({
       if (instance.bodyUsed) {
         throw new Error("cannot clone body after it is used");
       }
-      if (body instanceof import_node_stream.default && typeof body.getBoundary !== "function") {
-        p1 = new import_node_stream.PassThrough({ highWaterMark });
-        p2 = new import_node_stream.PassThrough({ highWaterMark });
+      if (body instanceof import_node_stream2.default && typeof body.getBoundary !== "function") {
+        p1 = new import_node_stream2.PassThrough({ highWaterMark });
+        p2 = new import_node_stream2.PassThrough({ highWaterMark });
         body.pipe(p1);
         body.pipe(p2);
         instance[INTERNALS].stream = p1;
@@ -11088,7 +11900,7 @@ var init_body = __esm({
       if (body && typeof body.getBoundary === "function") {
         return `multipart/form-data;boundary=${getNonSpecFormDataBoundary(body)}`;
       }
-      if (body instanceof import_node_stream.default) {
+      if (body instanceof import_node_stream2.default) {
         return null;
       }
       return "text/plain;charset=UTF-8";
@@ -11862,7 +12674,7 @@ function fetch2(url, options_) {
       const abort = () => {
         const error = new AbortError("The operation was aborted.");
         reject(error);
-        if (request.body && request.body instanceof import_node_stream2.default.Readable) {
+        if (request.body && request.body instanceof import_node_stream3.default.Readable) {
           request.body.destroy(error);
         }
         if (!response || !response.body) {
@@ -11961,7 +12773,7 @@ function fetch2(url, options_) {
                   requestOptions.headers.delete(name);
                 }
               }
-              if (response_.statusCode !== 303 && request.body && options_.body instanceof import_node_stream2.default.Readable) {
+              if (response_.statusCode !== 303 && request.body && options_.body instanceof import_node_stream3.default.Readable) {
                 reject(new FetchError("Cannot follow redirect with body being a readable stream", "unsupported-redirect"));
                 finalize();
                 return;
@@ -11988,7 +12800,7 @@ function fetch2(url, options_) {
             signal.removeEventListener("abort", abortAndFinalize);
           });
         }
-        let body = (0, import_node_stream2.pipeline)(response_, new import_node_stream2.PassThrough(), (error) => {
+        let body = (0, import_node_stream3.pipeline)(response_, new import_node_stream3.PassThrough(), (error) => {
           if (error) {
             reject(error);
           }
@@ -12016,7 +12828,7 @@ function fetch2(url, options_) {
           finishFlush: import_node_zlib.default.Z_SYNC_FLUSH
         };
         if (codings === "gzip" || codings === "x-gzip") {
-          body = (0, import_node_stream2.pipeline)(body, import_node_zlib.default.createGunzip(zlibOptions), (error) => {
+          body = (0, import_node_stream3.pipeline)(body, import_node_zlib.default.createGunzip(zlibOptions), (error) => {
             if (error) {
               reject(error);
             }
@@ -12026,20 +12838,20 @@ function fetch2(url, options_) {
           return;
         }
         if (codings === "deflate" || codings === "x-deflate") {
-          const raw = (0, import_node_stream2.pipeline)(response_, new import_node_stream2.PassThrough(), (error) => {
+          const raw = (0, import_node_stream3.pipeline)(response_, new import_node_stream3.PassThrough(), (error) => {
             if (error) {
               reject(error);
             }
           });
           raw.once("data", (chunk) => {
             if ((chunk[0] & 15) === 8) {
-              body = (0, import_node_stream2.pipeline)(body, import_node_zlib.default.createInflate(), (error) => {
+              body = (0, import_node_stream3.pipeline)(body, import_node_zlib.default.createInflate(), (error) => {
                 if (error) {
                   reject(error);
                 }
               });
             } else {
-              body = (0, import_node_stream2.pipeline)(body, import_node_zlib.default.createInflateRaw(), (error) => {
+              body = (0, import_node_stream3.pipeline)(body, import_node_zlib.default.createInflateRaw(), (error) => {
                 if (error) {
                   reject(error);
                 }
@@ -12057,7 +12869,7 @@ function fetch2(url, options_) {
           return;
         }
         if (codings === "br") {
-          body = (0, import_node_stream2.pipeline)(body, import_node_zlib.default.createBrotliDecompress(), (error) => {
+          body = (0, import_node_stream3.pipeline)(body, import_node_zlib.default.createBrotliDecompress(), (error) => {
             if (error) {
               reject(error);
             }
@@ -12105,13 +12917,13 @@ function fixResponseChunkedTransferBadEnding(request, errorCallback) {
     });
   });
 }
-var import_node_http2, import_node_https, import_node_zlib, import_node_stream2, import_node_buffer2, supportedSchemas;
+var import_node_http2, import_node_https, import_node_zlib, import_node_stream3, import_node_buffer2, supportedSchemas;
 var init_src = __esm({
   "../../node_modules/.pnpm/node-fetch@3.3.2/node_modules/node-fetch/src/index.js"() {
     import_node_http2 = __toESM(require("http"), 1);
     import_node_https = __toESM(require("https"), 1);
     import_node_zlib = __toESM(require("zlib"), 1);
-    import_node_stream2 = __toESM(require("stream"), 1);
+    import_node_stream3 = __toESM(require("stream"), 1);
     import_node_buffer2 = require("buffer");
     init_dist();
     init_body();
@@ -15687,9 +16499,9 @@ var require_util2 = __commonJS({
     exports2.removeUndefinedValuesInObject = removeUndefinedValuesInObject;
     exports2.isValidFile = isValidFile;
     exports2.getWellKnownCertificateConfigFileLocation = getWellKnownCertificateConfigFileLocation;
-    var fs11 = require("fs");
+    var fs12 = require("fs");
     var os3 = require("os");
-    var path7 = require("path");
+    var path8 = require("path");
     var WELL_KNOWN_CERTIFICATE_CONFIG_FILE = "certificate_config.json";
     var CLOUDSDK_CONFIG_DIRECTORY = "gcloud";
     function snakeToCamel(str) {
@@ -15781,7 +16593,7 @@ var require_util2 = __commonJS({
     function isValidFile(filePath) {
       return __async(this, null, function* () {
         try {
-          const stats = yield fs11.promises.lstat(filePath);
+          const stats = yield fs12.promises.lstat(filePath);
           return stats.isFile();
         } catch (e2) {
           return false;
@@ -15789,8 +16601,8 @@ var require_util2 = __commonJS({
       });
     }
     function getWellKnownCertificateConfigFileLocation() {
-      const configDir = process.env.CLOUDSDK_CONFIG || (_isWindows() ? path7.join(process.env.APPDATA || "", CLOUDSDK_CONFIG_DIRECTORY) : path7.join(process.env.HOME || "", ".config", CLOUDSDK_CONFIG_DIRECTORY));
-      return path7.join(configDir, WELL_KNOWN_CERTIFICATE_CONFIG_FILE);
+      const configDir = process.env.CLOUDSDK_CONFIG || (_isWindows() ? path8.join(process.env.APPDATA || "", CLOUDSDK_CONFIG_DIRECTORY) : path8.join(process.env.HOME || "", ".config", CLOUDSDK_CONFIG_DIRECTORY));
+      return path8.join(configDir, WELL_KNOWN_CERTIFICATE_CONFIG_FILE);
     }
     function _isWindows() {
       return os3.platform().startsWith("win");
@@ -17666,10 +18478,10 @@ var require_src5 = __commonJS({
       value: true
     });
     exports2.GoogleToken = void 0;
-    var fs11 = _interopRequireWildcard(require("fs"));
+    var fs12 = _interopRequireWildcard(require("fs"));
     var _gaxios = require_src2();
     var jws = _interopRequireWildcard(require_jws());
-    var path7 = _interopRequireWildcard(require("path"));
+    var path8 = _interopRequireWildcard(require("path"));
     var _util = require("util");
     function _interopRequireWildcard(e2, t2) {
       if ("function" == typeof WeakMap) var r2 = /* @__PURE__ */ new WeakMap(), n = /* @__PURE__ */ new WeakMap();
@@ -17909,7 +18721,7 @@ var require_src5 = __commonJS({
         });
       };
     }
-    var readFile = fs11.readFile ? (0, _util.promisify)(fs11.readFile) : /* @__PURE__ */ _asyncToGenerator(/* @__PURE__ */ _regenerator().m(function _callee() {
+    var readFile = fs12.readFile ? (0, _util.promisify)(fs12.readFile) : /* @__PURE__ */ _asyncToGenerator(/* @__PURE__ */ _regenerator().m(function _callee() {
       return _regenerator().w(function(_context) {
         while (1) switch (_context.n) {
           case 0:
@@ -18043,7 +18855,7 @@ var require_src5 = __commonJS({
             return _regenerator().w(function(_context2) {
               while (1) switch (_context2.n) {
                 case 0:
-                  ext = path7.extname(keyFile);
+                  ext = path8.extname(keyFile);
                   _t = ext;
                   _context2.n = _t === ".json" ? 1 : _t === ".der" ? 4 : _t === ".crt" ? 4 : _t === ".pem" ? 4 : _t === ".p12" ? 6 : _t === ".pfx" ? 6 : 7;
                   break;
@@ -19713,15 +20525,15 @@ var require_filesubjecttokensupplier = __commonJS({
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.FileSubjectTokenSupplier = void 0;
     var util_1 = require("util");
-    var fs11 = require("fs");
+    var fs12 = require("fs");
     var _a4;
-    var readFile = (0, util_1.promisify)((_a4 = fs11.readFile) != null ? _a4 : () => {
+    var readFile = (0, util_1.promisify)((_a4 = fs12.readFile) != null ? _a4 : () => {
     });
     var _a5;
-    var realpath = (0, util_1.promisify)((_a5 = fs11.realpath) != null ? _a5 : () => {
+    var realpath = (0, util_1.promisify)((_a5 = fs12.realpath) != null ? _a5 : () => {
     });
     var _a6;
-    var lstat = (0, util_1.promisify)((_a6 = fs11.lstat) != null ? _a6 : () => {
+    var lstat = (0, util_1.promisify)((_a6 = fs12.lstat) != null ? _a6 : () => {
     });
     var FileSubjectTokenSupplier = class {
       /**
@@ -19841,7 +20653,7 @@ var require_certificatesubjecttokensupplier = __commonJS({
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.CertificateSubjectTokenSupplier = exports2.InvalidConfigurationError = exports2.CertificateSourceUnavailableError = exports2.CERTIFICATE_CONFIGURATION_ENV_VARIABLE = void 0;
     var util_1 = require_util2();
-    var fs11 = require("fs");
+    var fs12 = require("fs");
     var crypto_1 = require("crypto");
     var https2 = require("https");
     exports2.CERTIFICATE_CONFIGURATION_ENV_VARIABLE = "GOOGLE_API_CERTIFICATE_CONFIG";
@@ -19936,7 +20748,7 @@ var require_certificatesubjecttokensupplier = __commonJS({
         const configPath = this.certificateConfigPath;
         let fileContents;
         try {
-          fileContents = yield fs11.promises.readFile(configPath, "utf8");
+          fileContents = yield fs12.promises.readFile(configPath, "utf8");
         } catch (err) {
           throw new CertificateSourceUnavailableError(`Failed to read certificate config file at: ${configPath}`);
         }
@@ -19959,14 +20771,14 @@ var require_certificatesubjecttokensupplier = __commonJS({
       return __async(this, null, function* () {
         let cert, key;
         try {
-          cert = yield fs11.promises.readFile(certPath);
+          cert = yield fs12.promises.readFile(certPath);
           new crypto_1.X509Certificate(cert);
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
           throw new CertificateSourceUnavailableError(`Failed to read certificate file at ${certPath}: ${message}`);
         }
         try {
-          key = yield fs11.promises.readFile(keyPath);
+          key = yield fs12.promises.readFile(keyPath);
           (0, crypto_1.createPrivateKey)(key);
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
@@ -19983,7 +20795,7 @@ var require_certificatesubjecttokensupplier = __commonJS({
           return JSON.stringify([leafCert.raw.toString("base64")]);
         }
         try {
-          const chainPems = yield fs11.promises.readFile(this.trustChainPath, "utf8");
+          const chainPems = yield fs12.promises.readFile(this.trustChainPath, "utf8");
           const pemBlocks = (_a4 = chainPems.match(/-----BEGIN CERTIFICATE-----[^-]+-----END CERTIFICATE-----/g)) != null ? _a4 : [];
           const chainCerts = pemBlocks.map((pem, index) => {
             try {
@@ -20685,7 +21497,7 @@ var require_pluggable_auth_handler = __commonJS({
     exports2.PluggableAuthHandler = exports2.ExecutableError = void 0;
     var executable_response_1 = require_executable_response();
     var childProcess2 = require("child_process");
-    var fs11 = require("fs");
+    var fs12 = require("fs");
     var ExecutableError = class extends Error {
       constructor(message, code) {
         super(`The executable failed with exit code: ${code} and error message: ${message}.`);
@@ -20771,14 +21583,14 @@ var require_pluggable_auth_handler = __commonJS({
           }
           let filePath;
           try {
-            filePath = yield fs11.promises.realpath(this.outputFile);
+            filePath = yield fs12.promises.realpath(this.outputFile);
           } catch (e2) {
             return void 0;
           }
-          if (!(yield fs11.promises.lstat(filePath)).isFile()) {
+          if (!(yield fs12.promises.lstat(filePath)).isFile()) {
             return void 0;
           }
-          const responseString = yield fs11.promises.readFile(filePath, {
+          const responseString = yield fs12.promises.readFile(filePath, {
             encoding: "utf8"
           });
           if (responseString === "") {
@@ -21205,11 +22017,11 @@ var require_googleauth = __commonJS({
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.GoogleAuth = exports2.GoogleAuthExceptionMessages = void 0;
     var child_process_1 = require("child_process");
-    var fs11 = require("fs");
+    var fs12 = require("fs");
     var gaxios_1 = require_src2();
     var gcpMetadata = require_src4();
     var os3 = require("os");
-    var path7 = require("path");
+    var path8 = require("path");
     var crypto_1 = require_crypto3();
     var computeclient_1 = require_computeclient();
     var idtokenclient_1 = require_idtokenclient();
@@ -21507,12 +22319,12 @@ var require_googleauth = __commonJS({
           } else {
             const home = process.env["HOME"];
             if (home) {
-              location = path7.join(home, ".config");
+              location = path8.join(home, ".config");
             }
           }
           if (location) {
-            location = path7.join(location, "gcloud", "application_default_credentials.json");
-            if (!fs11.existsSync(location)) {
+            location = path8.join(location, "gcloud", "application_default_credentials.json");
+            if (!fs12.existsSync(location)) {
               location = null;
             }
           }
@@ -21535,8 +22347,8 @@ var require_googleauth = __commonJS({
             throw new Error("The file path is invalid.");
           }
           try {
-            filePath = fs11.realpathSync(filePath);
-            if (!fs11.lstatSync(filePath).isFile()) {
+            filePath = fs12.realpathSync(filePath);
+            if (!fs12.lstatSync(filePath).isFile()) {
               throw new Error();
             }
           } catch (err) {
@@ -21545,7 +22357,7 @@ var require_googleauth = __commonJS({
             }
             throw err;
           }
-          const readStream = fs11.createReadStream(filePath);
+          const readStream = fs12.createReadStream(filePath);
           return this.fromStream(readStream, options);
         });
       }
@@ -22020,8 +22832,8 @@ var require_googleauth = __commonJS({
         if (this.jsonContent) {
           return this._cacheClientFromJSON(this.jsonContent, this.clientOptions);
         } else if (this.keyFilename) {
-          const filePath = path7.resolve(this.keyFilename);
-          const stream = fs11.createReadStream(filePath);
+          const filePath = path8.resolve(this.keyFilename);
+          const stream = fs12.createReadStream(filePath);
           return yield this.fromStreamAsync(stream, this.clientOptions);
         } else if (this.apiKey) {
           const client = yield this.fromAPIKey(this.apiKey, this.clientOptions);
@@ -24391,11 +25203,12 @@ var page_exports = {};
 __export(page_exports, {
   Page: () => Page
 });
-var import_fs7, LIFECYCLE_NAME, Page;
+var import_fs7, LIFECYCLE_NAME, _keyPress_dec, _type_dec, _dragAndDrop_dec, _scroll_dec, _click_dec, _evaluate_dec, _waitForLoadState_dec, _screenshot_dec, _goForward_dec, _goBack_dec, _reload_dec, _goto_dec, _close_dec, _init, _Page, Page;
 var init_page = __esm({
   "lib/v3/understudy/page.ts"() {
     import_fs7 = require("fs");
     init_logger();
+    init_flowLogger();
     init_frame();
     init_frameLocator();
     init_deepLocator();
@@ -24415,22 +25228,33 @@ var init_page = __esm({
       domcontentloaded: "DOMContentLoaded",
       networkidle: "networkIdle"
     };
-    Page = class _Page {
+    _close_dec = [logAction("Page.close")], _goto_dec = [logAction("Page.goto")], _reload_dec = [logAction("Page.reload")], _goBack_dec = [logAction("Page.goBack")], _goForward_dec = [logAction("Page.goForward")], _screenshot_dec = [logAction("Page.screenshot")], _waitForLoadState_dec = [logAction("Page.waitForLoadState")], _evaluate_dec = [logAction("Page.evaluate")], _click_dec = [logAction("Page.click")], _scroll_dec = [logAction("Page.scroll")], _dragAndDrop_dec = [logAction("Page.dragAndDrop")], _type_dec = [logAction("Page.type")], _keyPress_dec = [logAction("Page.keyPress")];
+    _Page = class _Page {
       constructor(conn, mainSession, _targetId, mainFrameId, apiClient, browserIsRemote = false) {
         this.conn = conn;
         this.mainSession = mainSession;
         this._targetId = _targetId;
+        __runInitializers(_init, 5, this);
         /** Every CDP child session this page owns (top-level + adopted OOPIF sessions). */
         this.sessions = /* @__PURE__ */ new Map();
+        // sessionId -> session
+        /** Unified truth for frame topology + ownership. */
+        this.registry = void 0;
+        /** A convenience wrapper bound to the current main frame id (top-level session). */
+        this.mainFrameWrapper = void 0;
         /** Compact ordinal per frameId (used by snapshot encoding). */
         this.frameOrdinals = /* @__PURE__ */ new Map();
         this.nextOrdinal = 0;
         /** cache Frames per frameId so everyone uses the same one */
         this.frameCache = /* @__PURE__ */ new Map();
+        this.browserIsRemote = void 0;
+        /** Stable id for Frames created by this Page (use top-level TargetId). */
+        this.pageId = void 0;
         /** Cached current URL for synchronous page.url() */
         this._currentUrl = "about:blank";
         this.navigationCommandSeq = 0;
         this.latestNavigationCommandId = 0;
+        this.networkManager = void 0;
         /** Optional API client for routing page operations to the API */
         this.apiClient = null;
         this.consoleListeners = /* @__PURE__ */ new Set();
@@ -24856,9 +25680,6 @@ var init_page = __esm({
       mainFrame() {
         return this.mainFrameWrapper;
       }
-      /**
-       * Close this top-level page (tab). Best-effort via Target.closeTarget.
-       */
       close() {
         return __async(this, null, function* () {
           try {
@@ -24967,11 +25788,6 @@ var init_page = __esm({
           }
         }
       }
-      // -------- Convenience APIs delegated to the current main frame --------
-      /**
-       * Navigate the page; optionally wait for a lifecycle state.
-       * Waits on the **current** main frame and follows root swaps during navigation.
-       */
       goto(url, options) {
         return __async(this, null, function* () {
           var _a4, _b;
@@ -25024,9 +25840,6 @@ var init_page = __esm({
           }
         });
       }
-      /**
-       * Reload the page; optionally wait for a lifecycle state.
-       */
       reload(options) {
         return __async(this, null, function* () {
           var _a4, _b;
@@ -25061,9 +25874,6 @@ var init_page = __esm({
           }
         });
       }
-      /**
-       * Navigate back in history if possible; optionally wait for a lifecycle state.
-       */
       goBack(options) {
         return __async(this, null, function* () {
           var _a4, _b;
@@ -25104,9 +25914,6 @@ var init_page = __esm({
           }
         });
       }
-      /**
-       * Navigate forward in history if possible; optionally wait for a lifecycle state.
-       */
       goForward(options) {
         return __async(this, null, function* () {
           var _a4, _b;
@@ -25194,36 +26001,6 @@ var init_page = __esm({
           }
         });
       }
-      /**
-       * Capture a screenshot with Playwright-style options.
-       *
-       * @param options Optional screenshot configuration.
-       * @param options.animations Control CSS/Web animations during capture. Use
-       * "disabled" to fast-forward finite animations and pause infinite ones.
-       * @param options.caret Either hide the text caret (default) or leave it
-       * visible via "initial".
-       * @param options.clip Restrict capture to a specific rectangle (in CSS
-       * pixels). Cannot be combined with `fullPage`.
-       * @param options.fullPage Capture the full scrollable page instead of the
-       * current viewport.
-       * @param options.mask Array of locators that should be covered with an
-       * overlay while the screenshot is taken.
-       * @param options.maskColor CSS color used for the mask overlay (default
-       * `#FF00FF`).
-       * @param options.omitBackground Make the default page background transparent
-       * (PNG only).
-       * @param options.path File path to write the screenshot to. The file extension
-       * determines the image type when `type` is not explicitly provided.
-       * @param options.quality JPEG quality (0–100). Only applies when
-       * `type === "jpeg"`.
-       * @param options.scale Render scale: use "css" for one pixel per CSS pixel,
-       * otherwise the default "device" leverages the current device pixel ratio.
-       * @param options.style Additional CSS text injected into every frame before
-       * capture (removed afterwards).
-       * @param options.timeout Maximum capture duration in milliseconds before a
-       * timeout error is thrown.
-       * @param options.type Image format (`"png"` by default).
-       */
       screenshot(options) {
         return __async(this, null, function* () {
           var _a4, _b, _c, _d2, _e;
@@ -25326,22 +26103,11 @@ var init_page = __esm({
         withOrd.sort((a, b) => a.ord - b.ord);
         return withOrd.map(({ id }) => this.frameForId(id));
       }
-      /**
-       * Wait until the page reaches a lifecycle state on the current main frame.
-       * Mirrors Playwright's API signatures.
-       */
       waitForLoadState(state, timeoutMs) {
         return __async(this, null, function* () {
           yield this.waitForMainLoadState(state, timeoutMs != null ? timeoutMs : 15e3);
         });
       }
-      /**
-       * Evaluate a function or expression in the current main frame's main world.
-       * - If a string is provided, it is treated as a JS expression.
-       * - If a function is provided, it is stringified and invoked with the optional argument.
-       * - The return value should be JSON-serializable. Non-serializable objects will
-       *   best-effort serialize via JSON.stringify inside the page context.
-       */
       evaluate(pageFunctionOrExpression, arg) {
         return __async(this, null, function* () {
           var _a4;
@@ -25356,15 +26122,15 @@ var init_page = __esm({
             const fnSrc = pageFunctionOrExpression.toString();
             const argJson = JSON.stringify(arg);
             expression = `(() => {
-        const __fn = ${fnSrc};
-        const __arg = ${argJson};
-        try {
-          const __res = __fn(__arg);
-          return Promise.resolve(__res).then(v => {
-            try { return JSON.parse(JSON.stringify(v)); } catch { return v; }
-          });
-        } catch (e) { throw e; }
-      })()`;
+          const __fn = ${fnSrc};
+          const __arg = ${argJson};
+          try {
+            const __res = __fn(__arg);
+            return Promise.resolve(__res).then(v => {
+              try { return JSON.parse(JSON.stringify(v)); } catch { return v; }
+            });
+          } catch (e) { throw e; }
+        })()`;
           }
           const { result, exceptionDetails } = yield this.mainSession.send(
             "Runtime.evaluate",
@@ -25386,6 +26152,7 @@ var init_page = __esm({
        * Force the page viewport to an exact CSS size and device scale factor.
        * Ensures screenshots match width x height pixels when deviceScaleFactor = 1.
        */
+      // @logAction("Page.setViewportSize")  // disabled because it's pretty noisy, can always re-enable if needed for debugging
       setViewportSize(width, height, options) {
         return __async(this, null, function* () {
           var _a4;
@@ -25569,12 +26336,6 @@ var init_page = __esm({
           if (options == null ? void 0 : options.returnXpath) return [fromXpath != null ? fromXpath : "", toXpath != null ? toXpath : ""];
         });
       }
-      /**
-       * Type a string by dispatching keyDown/keyUp events per character.
-       * Focus must already be on the desired element. Uses CDP Input.dispatchKeyEvent
-       * and never falls back to Input.insertText. Optional delay applies between
-       * successive characters.
-       */
       type(text, options) {
         return __async(this, null, function* () {
           var _a4;
@@ -25647,11 +26408,6 @@ var init_page = __esm({
           }
         });
       }
-      /**
-       * Press a single key or key combination (keyDown then keyUp).
-       * For printable characters, uses the text path on keyDown; for named keys, sets key/code/VK.
-       * Supports key combinations with modifiers like "Cmd+A", "Ctrl+C", "Shift+Tab", etc.
-       */
       keyPress(key, options) {
         return __async(this, null, function* () {
           var _a4;
@@ -25999,6 +26755,22 @@ var init_page = __esm({
         });
       }
     };
+    _init = __decoratorStart(null);
+    __decorateElement(_init, 1, "close", _close_dec, _Page);
+    __decorateElement(_init, 1, "goto", _goto_dec, _Page);
+    __decorateElement(_init, 1, "reload", _reload_dec, _Page);
+    __decorateElement(_init, 1, "goBack", _goBack_dec, _Page);
+    __decorateElement(_init, 1, "goForward", _goForward_dec, _Page);
+    __decorateElement(_init, 1, "screenshot", _screenshot_dec, _Page);
+    __decorateElement(_init, 1, "waitForLoadState", _waitForLoadState_dec, _Page);
+    __decorateElement(_init, 1, "evaluate", _evaluate_dec, _Page);
+    __decorateElement(_init, 1, "click", _click_dec, _Page);
+    __decorateElement(_init, 1, "scroll", _scroll_dec, _Page);
+    __decorateElement(_init, 1, "dragAndDrop", _dragAndDrop_dec, _Page);
+    __decorateElement(_init, 1, "type", _type_dec, _Page);
+    __decorateElement(_init, 1, "keyPress", _keyPress_dec, _Page);
+    __decoratorMetadata(_init, _Page);
+    Page = _Page;
   }
 });
 
@@ -26093,6 +26865,7 @@ var import_fs8 = __toESM(require("fs"));
 var import_os2 = __toESM(require("os"));
 var import_path6 = __toESM(require("path"));
 var import_process2 = __toESM(require("process"));
+var import_uuid6 = require("uuid");
 
 // lib/utils.ts
 init_sdkErrors();
@@ -26583,9 +27356,9 @@ function transformSchema(schema, currentPath) {
   }
   return [schema, []];
 }
-function injectUrls(obj, path7, idToUrlMapping) {
+function injectUrls(obj, path8, idToUrlMapping) {
   var _a4, _b;
-  if (path7.length === 0) return;
+  if (path8.length === 0) return;
   const toId = (value) => {
     if (typeof value === "number") {
       return String(value);
@@ -26595,7 +27368,7 @@ function injectUrls(obj, path7, idToUrlMapping) {
     }
     return void 0;
   };
-  const [key, ...rest] = path7;
+  const [key, ...rest] = path8;
   if (key === "*") {
     if (Array.isArray(obj)) {
       if (rest.length === 0) {
@@ -26613,7 +27386,7 @@ function injectUrls(obj, path7, idToUrlMapping) {
   }
   if (obj && typeof obj === "object") {
     const record = obj;
-    if (path7.length === 1) {
+    if (path8.length === 1) {
       const fieldValue = record[key];
       const id = toId(fieldValue);
       if (id !== void 0) {
@@ -26673,8 +27446,8 @@ function loadApiKeyFromEnv(provider, logger) {
   }
   return void 0;
 }
-function trimTrailingTextNode(path7) {
-  return path7 == null ? void 0 : path7.replace(/\/text\(\)(\[\d+\])?$/iu, "");
+function trimTrailingTextNode(path8) {
+  return path8 == null ? void 0 : path8.replace(/\/text\(\)(\[\d+\])?$/iu, "");
 }
 function jsonSchemaToZod(schema) {
   switch (schema.type) {
@@ -27058,12 +27831,12 @@ var ActCache = class {
       const {
         value: entry,
         error,
-        path: path7
+        path: path8
       } = yield this.storage.readJson(`${context.cacheKey}.json`);
-      if (error && path7) {
+      if (error && path8) {
         this.logger({
           category: "cache",
-          message: `failed to read act cache entry: ${path7}`,
+          message: `failed to read act cache entry: ${path8}`,
           level: 2,
           auxiliary: {
             error: { value: String(error), type: "string" }
@@ -27104,11 +27877,11 @@ var ActCache = class {
         actionDescription: result.actionDescription,
         message: result.message
       };
-      const { error, path: path7 } = yield this.storage.writeJson(
+      const { error, path: path8 } = yield this.storage.writeJson(
         `${context.cacheKey}.json`,
         entry
       );
-      if (error && path7) {
+      if (error && path8) {
         this.logger({
           category: "cache",
           message: "failed to write act cache entry",
@@ -27226,11 +27999,11 @@ var ActCache = class {
   }
   refreshCacheEntry(context, entry) {
     return __async(this, null, function* () {
-      const { error, path: path7 } = yield this.storage.writeJson(
+      const { error, path: path8 } = yield this.storage.writeJson(
         `${context.cacheKey}.json`,
         entry
       );
-      if (error && path7) {
+      if (error && path8) {
         this.logger({
           category: "cache",
           message: "failed to update act cache entry after self-heal",
@@ -27372,14 +28145,14 @@ var AgentCache = class {
       const {
         value: entry,
         error,
-        path: path7
+        path: path8
       } = yield this.storage.readJson(
         `agent-${context.cacheKey}.json`
       );
-      if (error && path7) {
+      if (error && path8) {
         this.logger({
           category: "cache",
-          message: `failed to read agent cache entry: ${path7}`,
+          message: `failed to read agent cache entry: ${path8}`,
           level: 1,
           auxiliary: {
             error: { value: String(error), type: "string" }
@@ -27527,11 +28300,11 @@ var AgentCache = class {
         result: cloneForCache(result),
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
       };
-      const { error, path: path7 } = yield this.storage.writeJson(
+      const { error, path: path8 } = yield this.storage.writeJson(
         `agent-${context.cacheKey}.json`,
         entry
       );
-      if (error && path7) {
+      if (error && path8) {
         this.logger({
           category: "cache",
           message: "failed to write agent cache entry",
@@ -28531,6 +29304,7 @@ var SupportedPlaywrightAction = /* @__PURE__ */ ((SupportedPlaywrightAction2) =>
 // lib/v3/handlers/handlerUtils/actHandlerUtils.ts
 init_deepLocator();
 init_logger();
+init_flowLogger();
 init_sdkErrors();
 var UnderstudyCommandException = class extends Error {
   constructor(message) {
@@ -28574,6 +29348,11 @@ function performUnderstudyMethod(page, frame, method, rawXPath, args, domSettleT
       initialUrl,
       domSettleTimeoutMs
     };
+    SessionFileLogger.logUnderstudyActionEvent({
+      actionType: `Understudy.${method}`,
+      target: selectorRaw,
+      args: Array.from(args)
+    });
     try {
       const handler = (_a4 = METHOD_HANDLER_MAP[method]) != null ? _a4 : null;
       if (handler) {
@@ -28618,6 +29397,8 @@ function performUnderstudyMethod(page, frame, method, rawXPath, args, domSettleT
         }
       });
       throw new UnderstudyCommandException(msg);
+    } finally {
+      SessionFileLogger.logUnderstudyActionCompleted();
     }
   });
 }
@@ -30251,6 +31032,9 @@ function calculateCompressionStats(originalSize, compressedSize, screenshotCount
   };
 }
 
+// lib/v3/handlers/v3AgentHandler.ts
+init_flowLogger();
+
 // lib/v3/agent/utils/actionMapping.ts
 function mapToolResultToActions({
   toolCallName,
@@ -30351,12 +31135,12 @@ var V3AgentHandler = class {
         const baseModel = this.llmClient.getLanguageModel();
         const wrappedModel = (0, import_ai11.wrapLanguageModel)({
           model: baseModel,
-          middleware: {
+          middleware: __spreadValues({
             transformParams: (_0) => __async(this, [_0], function* ({ params }) {
               const { processedPrompt } = processMessages(params);
               return __spreadProps(__spreadValues({}, params), { prompt: processedPrompt });
             })
-          }
+          }, SessionFileLogger.createLlmLoggingMiddleware(baseModel.modelId))
         });
         const initialPageUrl = (yield this.v3.context.awaitActivePage()).url();
         return {
@@ -30801,6 +31585,8 @@ function compressGoogleConversationImages(items, keepMostRecentCount = 2) {
 }
 
 // lib/v3/agent/AnthropicCUAClient.ts
+init_flowLogger();
+var import_uuid2 = require("uuid");
 var AnthropicCUAClient = class extends AgentClient {
   constructor(type, modelName, userProvidedInstructions, clientOptions, tools) {
     super(type, modelName, userProvidedInstructions);
@@ -31119,6 +31905,13 @@ var AnthropicCUAClient = class extends AgentClient {
         if (thinking) {
           requestParams.thinking = thinking;
         }
+        const llmRequestId = (0, import_uuid2.v7)();
+        SessionFileLogger.logLlmRequest({
+          requestId: llmRequestId,
+          model: this.modelName,
+          operation: "CUA.getAction",
+          prompt: formatCuaPromptPreview(messages)
+        });
         const startTime = Date.now();
         const response = yield this.client.beta.messages.create(requestParams);
         const endTime = Date.now();
@@ -31128,6 +31921,14 @@ var AnthropicCUAClient = class extends AgentClient {
           output_tokens: response.usage.output_tokens,
           inference_time_ms: elapsedMs
         };
+        SessionFileLogger.logLlmResponse({
+          requestId: llmRequestId,
+          model: this.modelName,
+          operation: "CUA.getAction",
+          output: formatCuaResponsePreview(response.content),
+          inputTokens: response.usage.input_tokens,
+          outputTokens: response.usage.output_tokens
+        });
         this.lastMessageId = response.id;
         return {
           // Cast the response content to our internal type
@@ -31406,7 +32207,7 @@ var AnthropicCUAClient = class extends AgentClient {
             y
           }, input);
         } else if (action === "drag" || action === "left_click_drag") {
-          const path7 = input.path || (input.coordinate ? [
+          const path8 = input.path || (input.coordinate ? [
             {
               x: input.start_coordinate[0],
               y: input.start_coordinate[1]
@@ -31418,7 +32219,7 @@ var AnthropicCUAClient = class extends AgentClient {
           ] : []);
           return __spreadValues({
             type: "drag",
-            path: path7
+            path: path8
           }, input);
         } else if (action === "wait") {
           return __spreadValues({
@@ -31478,6 +32279,8 @@ var AnthropicCUAClient = class extends AgentClient {
 // lib/v3/agent/OpenAICUAClient.ts
 var import_openai = __toESM(require("openai"));
 init_sdkErrors();
+init_flowLogger();
+var import_uuid3 = require("uuid");
 var OpenAICUAClient = class extends AgentClient {
   constructor(type, modelName, userProvidedInstructions, clientOptions, tools) {
     super(type, modelName, userProvidedInstructions);
@@ -31750,6 +32553,13 @@ var OpenAICUAClient = class extends AgentClient {
         if (previousResponseId) {
           requestParams.previous_response_id = previousResponseId;
         }
+        const llmRequestId = (0, import_uuid3.v7)();
+        SessionFileLogger.logLlmRequest({
+          requestId: llmRequestId,
+          model: this.modelName,
+          operation: "CUA.getAction",
+          prompt: formatCuaPromptPreview(inputItems)
+        });
         const startTime = Date.now();
         const response = yield this.client.responses.create(requestParams);
         const endTime = Date.now();
@@ -31759,6 +32569,14 @@ var OpenAICUAClient = class extends AgentClient {
           output_tokens: response.usage.output_tokens,
           inference_time_ms: elapsedMs
         };
+        SessionFileLogger.logLlmResponse({
+          requestId: llmRequestId,
+          model: this.modelName,
+          operation: "CUA.getAction",
+          output: formatCuaResponsePreview(response.output),
+          inputTokens: response.usage.input_tokens,
+          outputTokens: response.usage.output_tokens
+        });
         this.lastResponseId = response.id;
         return {
           output: response.output,
@@ -32127,6 +32945,8 @@ function mapJsonTypeToGoogleType(jsonType) {
 }
 
 // lib/v3/agent/GoogleCUAClient.ts
+init_flowLogger();
+var import_uuid4 = require("uuid");
 var GoogleCUAClient = class extends AgentClient {
   constructor(type, modelName, userProvidedInstructions, clientOptions, tools) {
     super(type, modelName, userProvidedInstructions);
@@ -32308,6 +33128,13 @@ var GoogleCUAClient = class extends AgentClient {
         const baseDelayS = 1;
         let lastError = null;
         let response = null;
+        const llmRequestId = (0, import_uuid4.v7)();
+        SessionFileLogger.logLlmRequest({
+          requestId: llmRequestId,
+          model: this.modelName,
+          operation: "CUA.generateContent",
+          prompt: formatCuaPromptPreview(compressedHistory)
+        });
         for (let attempt = 0; attempt < maxRetries; attempt++) {
           try {
             if (attempt > 0) {
@@ -32351,6 +33178,14 @@ var GoogleCUAClient = class extends AgentClient {
         const endTime = Date.now();
         const elapsedMs = endTime - startTime;
         const { usageMetadata } = response;
+        SessionFileLogger.logLlmResponse({
+          requestId: llmRequestId,
+          model: this.modelName,
+          operation: "CUA.generateContent",
+          output: formatCuaResponsePreview(response),
+          inputTokens: usageMetadata == null ? void 0 : usageMetadata.promptTokenCount,
+          outputTokens: usageMetadata == null ? void 0 : usageMetadata.candidatesTokenCount
+        });
         const result = yield this.processResponse(response, logger);
         if (response.candidates && response.candidates[0]) {
           const sanitizedContent = JSON.parse(
@@ -33543,6 +34378,7 @@ var AgentProvider = class _AgentProvider {
 };
 
 // lib/v3/handlers/v3CuaAgentHandler.ts
+init_flowLogger();
 var V3CuaAgentHandler = class {
   constructor(v3, logger, options, tools) {
     this.v3 = v3;
@@ -33578,7 +34414,19 @@ var V3CuaAgentHandler = class {
           }
         }
         yield new Promise((r2) => setTimeout(r2, 300));
-        yield this.executeAction(action);
+        const shouldLog = action.type !== "screenshot";
+        if (shouldLog) {
+          SessionFileLogger.logUnderstudyActionEvent({
+            actionType: `v3CUA.${action.type}`,
+            target: this.computePointerTarget(action),
+            args: [action]
+          });
+        }
+        try {
+          yield this.executeAction(action);
+        } finally {
+          if (shouldLog) SessionFileLogger.logUnderstudyActionCompleted();
+        }
         action.timestamp = Date.now();
         yield new Promise((r2) => setTimeout(r2, waitBetween));
         try {
@@ -33808,13 +34656,13 @@ var V3CuaAgentHandler = class {
           return { success: true };
         }
         case "drag": {
-          const { path: path7 } = action;
-          if (Array.isArray(path7) && path7.length >= 2) {
-            const start = path7[0];
-            const end = path7[path7.length - 1];
+          const { path: path8 } = action;
+          if (Array.isArray(path8) && path8.length >= 2) {
+            const start = path8[0];
+            const end = path8[path8.length - 1];
             if (recording) {
               const xps = yield page.dragAndDrop(start.x, start.y, end.x, end.y, {
-                steps: Math.min(20, Math.max(5, path7.length)),
+                steps: Math.min(20, Math.max(5, path8.length)),
                 delay: 10,
                 returnXpath: true
               });
@@ -33836,7 +34684,7 @@ var V3CuaAgentHandler = class {
               }
             } else {
               yield page.dragAndDrop(start.x, start.y, end.x, end.y, {
-                steps: Math.min(20, Math.max(5, path7.length)),
+                steps: Math.min(20, Math.max(5, path8.length)),
                 delay: 10
               });
             }
@@ -33905,6 +34753,10 @@ var V3CuaAgentHandler = class {
       }
     });
   }
+  // helper to make pointer target human-readable for logging
+  computePointerTarget(action) {
+    return typeof action.x === "number" && typeof action.y === "number" ? `(${action.x}, ${action.y})` : typeof action.selector === "string" ? action.selector : typeof action.input === "string" ? action.input : typeof action.description === "string" ? action.description : void 0;
+  }
   ensureXPath(value) {
     if (typeof value !== "string") return null;
     const trimmed = value.trim();
@@ -34072,7 +34924,7 @@ function createBrowserbaseSession(apiKey, projectId, params, resumeSessionId) {
 }
 
 // ../../node_modules/.pnpm/chrome-launcher@1.2.0/node_modules/chrome-launcher/dist/chrome-launcher.js
-var fs6 = __toESM(require("fs"), 1);
+var fs7 = __toESM(require("fs"), 1);
 var net = __toESM(require("net"), 1);
 
 // ../../node_modules/.pnpm/chrome-launcher@1.2.0/node_modules/chrome-launcher/dist/chrome-finder.js
@@ -34519,15 +35371,15 @@ function toWSLPath(dir, fallback) {
     return fallback;
   }
 }
-function getLocalAppDataPath(path7) {
+function getLocalAppDataPath(path8) {
   const userRegExp = /\/mnt\/([a-z])\/Users\/([^\/:]+)\/AppData\//;
-  const results = userRegExp.exec(path7) || [];
+  const results = userRegExp.exec(path8) || [];
   return `/mnt/${results[1]}/Users/${results[2]}/AppData/Local`;
 }
-function getWSLLocalAppDataPath(path7) {
+function getWSLLocalAppDataPath(path8) {
   const userRegExp = /\/([a-z])\/Users\/([^\/:]+)\/AppData\//;
-  const results = userRegExp.exec(path7) || [];
-  return toWSLPath(`${results[1]}:\\Users\\${results[2]}\\AppData\\Local`, getLocalAppDataPath(path7));
+  const results = userRegExp.exec(path8) || [];
+  return toWSLPath(`${results[1]}:\\Users\\${results[2]}\\AppData\\Local`, getLocalAppDataPath(path8));
 }
 function makeUnixTmpDir() {
   return import_child_process.default.execSync("mktemp -d -t lighthouse.XXXXXXX").toString().trim();
@@ -34852,7 +35704,7 @@ var Launcher = class _Launcher {
     this.opts = opts;
     this.tmpDirandPidFileReady = false;
     this.remoteDebuggingPipes = null;
-    this.fs = moduleOverrides.fs || fs6;
+    this.fs = moduleOverrides.fs || fs7;
     this.spawn = moduleOverrides.spawn || import_child_process3.spawn;
     lighthouse_logger_default.setLevel(defaults(this.opts.logLevel, "silent"));
     this.startingUrl = defaults(this.opts.startingUrl, "about:blank");
@@ -35170,6 +36022,7 @@ init_sdkErrors();
 
 // lib/v3/llm/aisdk.ts
 var import_ai13 = require("ai");
+var import_uuid5 = require("uuid");
 
 // lib/v3/llm/LLMClient.ts
 var import_ai12 = require("ai");
@@ -35191,6 +36044,7 @@ var LLMClient = class {
 };
 
 // lib/v3/llm/aisdk.ts
+init_flowLogger();
 var AISdkClient = class extends LLMClient {
   constructor({
     model,
@@ -35284,6 +36138,16 @@ var AISdkClient = class extends LLMClient {
       const isGPT5 = this.model.modelId.includes("gpt-5");
       const isGPT51 = this.model.modelId.includes("gpt-5.1");
       if (options.response_model) {
+        const llmRequestId2 = (0, import_uuid5.v7)();
+        const promptPreview2 = formatLlmPromptPreview(options.messages, {
+          hasSchema: true
+        });
+        SessionFileLogger.logLlmRequest({
+          requestId: llmRequestId2,
+          model: this.model.modelId,
+          operation: "generateObject",
+          prompt: promptPreview2
+        });
         try {
           objectResponse = yield (0, import_ai13.generateObject)({
             model: this.model,
@@ -35299,6 +36163,12 @@ var AISdkClient = class extends LLMClient {
             } : void 0
           });
         } catch (err) {
+          SessionFileLogger.logLlmResponse({
+            requestId: llmRequestId2,
+            model: this.model.modelId,
+            operation: "generateObject",
+            output: `[error: ${err instanceof Error ? err.message : "unknown"}]`
+          });
           if (import_ai13.NoObjectGeneratedError.isInstance(err)) {
             (_g = this.logger) == null ? void 0 : _g.call(this, {
               category: "AISDK error",
@@ -35345,6 +36215,14 @@ var AISdkClient = class extends LLMClient {
             total_tokens: (_l = objectResponse.usage.totalTokens) != null ? _l : 0
           }
         };
+        SessionFileLogger.logLlmResponse({
+          requestId: llmRequestId2,
+          model: this.model.modelId,
+          operation: "generateObject",
+          output: JSON.stringify(objectResponse.object),
+          inputTokens: objectResponse.usage.inputTokens,
+          outputTokens: objectResponse.usage.outputTokens
+        });
         (_m = this.logger) == null ? void 0 : _m.call(this, {
           category: "aisdk",
           message: "response",
@@ -35376,13 +36254,35 @@ var AISdkClient = class extends LLMClient {
           };
         }
       }
-      const textResponse = yield (0, import_ai13.generateText)({
-        model: this.model,
-        messages: formattedMessages,
-        tools: Object.keys(tools).length > 0 ? tools : void 0,
-        toolChoice: Object.keys(tools).length > 0 ? options.tool_choice === "required" ? "required" : options.tool_choice === "none" ? "none" : "auto" : void 0,
-        temperature: options.temperature
+      const llmRequestId = (0, import_uuid5.v7)();
+      const toolCount = Object.keys(tools).length;
+      const promptPreview = formatLlmPromptPreview(options.messages, {
+        toolCount
       });
+      SessionFileLogger.logLlmRequest({
+        requestId: llmRequestId,
+        model: this.model.modelId,
+        operation: "generateText",
+        prompt: promptPreview
+      });
+      let textResponse;
+      try {
+        textResponse = yield (0, import_ai13.generateText)({
+          model: this.model,
+          messages: formattedMessages,
+          tools: Object.keys(tools).length > 0 ? tools : void 0,
+          toolChoice: Object.keys(tools).length > 0 ? options.tool_choice === "required" ? "required" : options.tool_choice === "none" ? "none" : "auto" : void 0,
+          temperature: options.temperature
+        });
+      } catch (err) {
+        SessionFileLogger.logLlmResponse({
+          requestId: llmRequestId,
+          model: this.model.modelId,
+          operation: "generateText",
+          output: `[error: ${err instanceof Error ? err.message : "unknown"}]`
+        });
+        throw err;
+      }
       const transformedToolCalls = (textResponse.toolCalls || []).map(
         (toolCall) => ({
           id: toolCall.toolCallId || `call_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
@@ -35417,6 +36317,14 @@ var AISdkClient = class extends LLMClient {
           total_tokens: (_r = textResponse.usage.totalTokens) != null ? _r : 0
         }
       };
+      SessionFileLogger.logLlmResponse({
+        requestId: llmRequestId,
+        model: this.model.modelId,
+        operation: "generateText",
+        output: textResponse.text || (transformedToolCalls.length > 0 ? `[${transformedToolCalls.length} tool calls]` : ""),
+        inputTokens: textResponse.usage.inputTokens,
+        outputTokens: textResponse.usage.outputTokens
+      });
       (_s = this.logger) == null ? void 0 : _s.call(this, {
         category: "aisdk",
         message: "response",
@@ -43213,37 +44121,37 @@ function createOpenAI(options = {}) {
   );
   const createChatModel = (modelId) => new OpenAIChatLanguageModel(modelId, {
     provider: `${providerName}.chat`,
-    url: ({ path: path7 }) => `${baseURL}${path7}`,
+    url: ({ path: path8 }) => `${baseURL}${path8}`,
     headers: getHeaders,
     fetch: options.fetch
   });
   const createCompletionModel = (modelId) => new OpenAICompletionLanguageModel(modelId, {
     provider: `${providerName}.completion`,
-    url: ({ path: path7 }) => `${baseURL}${path7}`,
+    url: ({ path: path8 }) => `${baseURL}${path8}`,
     headers: getHeaders,
     fetch: options.fetch
   });
   const createEmbeddingModel = (modelId) => new OpenAIEmbeddingModel(modelId, {
     provider: `${providerName}.embedding`,
-    url: ({ path: path7 }) => `${baseURL}${path7}`,
+    url: ({ path: path8 }) => `${baseURL}${path8}`,
     headers: getHeaders,
     fetch: options.fetch
   });
   const createImageModel = (modelId) => new OpenAIImageModel(modelId, {
     provider: `${providerName}.image`,
-    url: ({ path: path7 }) => `${baseURL}${path7}`,
+    url: ({ path: path8 }) => `${baseURL}${path8}`,
     headers: getHeaders,
     fetch: options.fetch
   });
   const createTranscriptionModel = (modelId) => new OpenAITranscriptionModel(modelId, {
     provider: `${providerName}.transcription`,
-    url: ({ path: path7 }) => `${baseURL}${path7}`,
+    url: ({ path: path8 }) => `${baseURL}${path8}`,
     headers: getHeaders,
     fetch: options.fetch
   });
   const createSpeechModel = (modelId) => new OpenAISpeechModel(modelId, {
     provider: `${providerName}.speech`,
-    url: ({ path: path7 }) => `${baseURL}${path7}`,
+    url: ({ path: path8 }) => `${baseURL}${path8}`,
     headers: getHeaders,
     fetch: options.fetch
   });
@@ -43258,7 +44166,7 @@ function createOpenAI(options = {}) {
   const createResponsesModel = (modelId) => {
     return new OpenAIResponsesLanguageModel(modelId, {
       provider: `${providerName}.responses`,
-      url: ({ path: path7 }) => `${baseURL}${path7}`,
+      url: ({ path: path8 }) => `${baseURL}${path8}`,
       headers: getHeaders,
       fetch: options.fetch,
       fileIdPrefixes: ["file-"]
@@ -53437,7 +54345,7 @@ function createXai(options = {}) {
   const createImageModel = (modelId) => {
     return new OpenAICompatibleImageModel(modelId, {
       provider: "xai.image",
-      url: ({ path: path7 }) => `${baseURL}${path7}`,
+      url: ({ path: path8 }) => `${baseURL}${path8}`,
       headers: getHeaders,
       fetch: options.fetch,
       errorStructure: xaiErrorStructure
@@ -57704,14 +58612,14 @@ function createAzure(options = {}) {
     description: "Azure OpenAI resource name"
   });
   const apiVersion = (_a4 = options.apiVersion) != null ? _a4 : "v1";
-  const url = ({ path: path7, modelId }) => {
+  const url = ({ path: path8, modelId }) => {
     var _a22;
     const baseUrlPrefix = (_a22 = options.baseURL) != null ? _a22 : `https://${getResourceName()}.openai.azure.com/openai`;
     let fullUrl;
     if (options.useDeploymentBasedUrls) {
-      fullUrl = new URL(`${baseUrlPrefix}/deployments/${modelId}${path7}`);
+      fullUrl = new URL(`${baseUrlPrefix}/deployments/${modelId}${path8}`);
     } else {
-      fullUrl = new URL(`${baseUrlPrefix}/v1${path7}`);
+      fullUrl = new URL(`${baseUrlPrefix}/v1${path8}`);
     }
     fullUrl.searchParams.set("api-version", apiVersion);
     return fullUrl.toString();
@@ -58627,7 +59535,7 @@ function createGroq(options = {}) {
   );
   const createChatModel = (modelId) => new GroqChatLanguageModel(modelId, {
     provider: "groq.chat",
-    url: ({ path: path7 }) => `${baseURL}${path7}`,
+    url: ({ path: path8 }) => `${baseURL}${path8}`,
     headers: getHeaders,
     fetch: options.fetch
   });
@@ -58642,7 +59550,7 @@ function createGroq(options = {}) {
   const createTranscriptionModel = (modelId) => {
     return new GroqTranscriptionModel(modelId, {
       provider: "groq.transcription",
-      url: ({ path: path7 }) => `${baseURL}${path7}`,
+      url: ({ path: path8 }) => `${baseURL}${path8}`,
       headers: getHeaders,
       fetch: options.fetch
     });
@@ -58697,7 +59605,7 @@ function createCerebras(options = {}) {
   const createLanguageModel = (modelId) => {
     return new OpenAICompatibleChatLanguageModel(modelId, {
       provider: `cerebras.chat`,
-      url: ({ path: path7 }) => `${baseURL}${path7}`,
+      url: ({ path: path8 }) => `${baseURL}${path8}`,
       headers: getHeaders,
       fetch: options.fetch,
       errorStructure: cerebrasErrorStructure,
@@ -58816,7 +59724,7 @@ function createTogetherAI(options = {}) {
   );
   const getCommonModelConfig = (modelType) => ({
     provider: `togetherai.${modelType}`,
-    url: ({ path: path7 }) => `${baseURL}${path7}`,
+    url: ({ path: path8 }) => `${baseURL}${path8}`,
     headers: getHeaders,
     fetch: options.fetch
   });
@@ -59702,7 +60610,7 @@ function createDeepSeek(options = {}) {
   const createLanguageModel = (modelId) => {
     return new OpenAICompatibleChatLanguageModel(modelId, {
       provider: `deepseek.chat`,
-      url: ({ path: path7 }) => `${baseURL}${path7}`,
+      url: ({ path: path8 }) => `${baseURL}${path8}`,
       headers: getHeaders,
       fetch: options.fetch,
       metadataExtractor: deepSeekMetadataExtractor
@@ -61412,13 +62320,13 @@ function createOllama(options = {}) {
   }, options.headers);
   const createCompletionModel = (modelId, settings = {}) => new OllamaCompletionLanguageModel(modelId, settings, {
     provider: `${providerName}.completion`,
-    url: ({ path: path7 }) => `${baseURL}${path7}`,
+    url: ({ path: path8 }) => `${baseURL}${path8}`,
     headers: getHeaders,
     fetch: options.fetch
   });
   const createEmbeddingModel = (modelId, settings = {}) => new OllamaEmbeddingModel(modelId, settings, {
     provider: `${providerName}.embedding`,
-    url: ({ path: path7 }) => `${baseURL}${path7}`,
+    url: ({ path: path8 }) => `${baseURL}${path8}`,
     headers: getHeaders,
     fetch: options.fetch
   });
@@ -61433,7 +62341,7 @@ function createOllama(options = {}) {
   const createResponsesModel = (modelId) => {
     return new OllamaResponsesLanguageModel(modelId, {
       provider: `${providerName}.responses`,
-      url: ({ path: path7 }) => `${baseURL}${path7}`,
+      url: ({ path: path8 }) => `${baseURL}${path8}`,
       headers: getHeaders,
       fetch: options.fetch
     });
@@ -61875,6 +62783,8 @@ var CdpConnection = class _CdpConnection {
     this.inflight = /* @__PURE__ */ new Map();
     this.eventHandlers = /* @__PURE__ */ new Map();
     this.sessions = /* @__PURE__ */ new Map();
+    /** Maps sessionId -> targetId (1:1 mapping) */
+    this.sessionToTarget = /* @__PURE__ */ new Map();
     this.id = null;
     // root
     this.transportCloseHandlers = /* @__PURE__ */ new Set();
@@ -61931,7 +62841,7 @@ var CdpConnection = class _CdpConnection {
   }
   send(method, params) {
     return __async(this, null, function* () {
-      var _a4;
+      var _a4, _b;
       const id = this.nextId++;
       const payload = { id, method, params };
       const stack = (_a4 = new Error().stack) == null ? void 0 : _a4.split("\n").slice(1, 4).join("\n");
@@ -61946,6 +62856,7 @@ var CdpConnection = class _CdpConnection {
           ts: Date.now()
         });
       });
+      (_b = this.cdpLogger) == null ? void 0 : _b.call(this, { method, params, targetId: null });
       this.ws.send(JSON.stringify(payload));
       return p;
     });
@@ -61982,6 +62893,7 @@ var CdpConnection = class _CdpConnection {
         session = new CdpSession(this, sessionId);
         this.sessions.set(sessionId, session);
       }
+      this.sessionToTarget.set(sessionId, targetId);
       return session;
     });
   }
@@ -61992,6 +62904,7 @@ var CdpConnection = class _CdpConnection {
     });
   }
   onMessage(json) {
+    var _a4;
     const msg = JSON.parse(json);
     if ("id" in msg) {
       const rec = this.inflight.get(msg.id);
@@ -62010,6 +62923,7 @@ var CdpConnection = class _CdpConnection {
         if (!this.sessions.has(p.sessionId)) {
           this.sessions.set(p.sessionId, new CdpSession(this, p.sessionId));
         }
+        this.sessionToTarget.set(p.sessionId, p.targetInfo.targetId);
       } else if (msg.method === "Target.detachedFromTarget") {
         const p = msg.params;
         for (const [id, entry] of this.inflight.entries()) {
@@ -62019,8 +62933,19 @@ var CdpConnection = class _CdpConnection {
           }
         }
         this.sessions.delete(p.sessionId);
+        this.sessionToTarget.delete(p.sessionId);
+      } else if (msg.method === "Target.targetDestroyed") {
+        const p = msg.params;
+        for (const [sessionId2, targetId2] of this.sessionToTarget.entries()) {
+          if (targetId2 === p.targetId) {
+            this.sessionToTarget.delete(sessionId2);
+            break;
+          }
+        }
       }
       const { method, params, sessionId } = msg;
+      const targetId = this.sessionToTarget.get(sessionId) || sessionId;
+      (_a4 = this.cdpEventLogger) == null ? void 0 : _a4.call(this, { method, params, targetId });
       if (sessionId) {
         const session = this.sessions.get(sessionId);
         session == null ? void 0 : session.dispatch(method, params);
@@ -62031,7 +62956,7 @@ var CdpConnection = class _CdpConnection {
     }
   }
   _sendViaSession(sessionId, method, params) {
-    var _a4;
+    var _a4, _b, _c;
     const id = this.nextId++;
     const payload = { id, method, params, sessionId };
     const stack = (_a4 = new Error().stack) == null ? void 0 : _a4.split("\n").slice(1, 4).join("\n");
@@ -62046,6 +62971,8 @@ var CdpConnection = class _CdpConnection {
         ts: Date.now()
       });
     });
+    const targetId = (_b = this.sessionToTarget.get(sessionId)) != null ? _b : null;
+    (_c = this.cdpLogger) == null ? void 0 : _c.call(this, { method, params, targetId });
     this.ws.send(JSON.stringify(payload));
     return p;
   }
@@ -63081,7 +64008,7 @@ var StagehandAPIClient = class {
       }
     });
   }
-  request(path7, options) {
+  request(path8, options) {
     return __async(this, null, function* () {
       var _a4;
       const defaultHeaders = {
@@ -63099,7 +64026,7 @@ var StagehandAPIClient = class {
         defaultHeaders["Content-Type"] = "application/json";
       }
       const response = yield this.fetchWithCookies(
-        `${(_a4 = process.env.STAGEHAND_API_URL) != null ? _a4 : "https://api.stagehand.browserbase.com/v1"}${path7}`,
+        `${(_a4 = process.env.STAGEHAND_API_URL) != null ? _a4 : "https://api.stagehand.browserbase.com/v1"}${path8}`,
         __spreadProps(__spreadValues({}, options), {
           headers: __spreadValues(__spreadValues({}, defaultHeaders), options.headers)
         })
@@ -63110,6 +64037,7 @@ var StagehandAPIClient = class {
 };
 
 // lib/v3/v3.ts
+init_flowLogger();
 init_sdkErrors();
 var DEFAULT_MODEL_NAME = "openai/gpt-4.1-mini";
 var DEFAULT_VIEWPORT = { width: 1288, height: 711 };
@@ -63135,15 +64063,27 @@ function resolveModelConfiguration(model) {
   return { modelName: DEFAULT_MODEL_NAME };
 }
 import_dotenv.default.config({ path: ".env" });
+var _observe_dec, _extract_dec, _act_dec, _init2;
+_act_dec = [logStagehandStep("Stagehand.act", "ACT")], _extract_dec = [logStagehandStep("Stagehand.extract", "EXTRACT")], _observe_dec = [logStagehandStep("Stagehand.observe", "OBSERVE")];
 var _V3 = class _V3 {
   constructor(opts) {
+    __runInitializers(_init2, 5, this);
+    this.opts = void 0;
     this.state = { kind: "UNINITIALIZED" };
     this.actHandler = null;
     this.extractHandler = null;
     this.observeHandler = null;
     this.ctx = null;
+    this.llmClient = void 0;
+    this.modelName = void 0;
+    this.modelClientOptions = void 0;
+    this.llmProvider = void 0;
     this.overrideLlmClients = /* @__PURE__ */ new Map();
+    this.domSettleTimeoutMs = void 0;
     this._isClosing = false;
+    this.browserbaseSessionId = void 0;
+    this.browserbaseSessionUrl = void 0;
+    this.browserbaseDebugUrl = void 0;
     this._onCdpClosed = (why) => {
       if (this.state.kind === "BROWSERBASE") {
         void this._logBrowserbaseSessionStatus();
@@ -63154,8 +64094,14 @@ var _V3 = class _V3 {
     this.experimental = false;
     this.logInferenceToFile = false;
     this.disableAPI = false;
+    this.externalLogger = void 0;
     this.verbose = 1;
+    this.stagehandLogger = void 0;
     this._history = [];
+    this.instanceId = void 0;
+    this.cacheStorage = void 0;
+    this.actCache = void 0;
+    this.agentCache = void 0;
     this.apiClient = null;
     this.stagehandMetrics = {
       actPromptTokens: 0,
@@ -63184,11 +64130,11 @@ var _V3 = class _V3 {
       totalCachedInputTokens: 0,
       totalInferenceTimeMs: 0
     };
-    var _a4, _b, _c, _d2, _e, _f, _g;
+    var _a4, _b, _c, _d2;
     _V3._installProcessGuards();
     this.externalLogger = opts.logger;
     this.verbose = (_a4 = opts.verbose) != null ? _a4 : 1;
-    this.instanceId = (_d2 = (_c = (_b = globalThis.crypto) == null ? void 0 : _b.randomUUID) == null ? void 0 : _c.call(_b)) != null ? _d2 : `${Date.now()}-${Math.floor(Math.random() * 1e9)}`;
+    this.instanceId = (0, import_uuid6.v7)();
     const loggerOptions = {
       pretty: true,
       level: "info"
@@ -63211,11 +64157,11 @@ var _V3 = class _V3 {
     }
     const { modelName, clientOptions } = resolveModelConfiguration(opts.model);
     this.modelName = modelName;
-    this.experimental = (_e = opts.experimental) != null ? _e : false;
-    this.logInferenceToFile = (_f = opts.logInferenceToFile) != null ? _f : false;
+    this.experimental = (_b = opts.experimental) != null ? _b : false;
+    this.logInferenceToFile = (_c = opts.logInferenceToFile) != null ? _c : false;
     this.llmProvider = new LLMProvider(this.logger);
     this.domSettleTimeoutMs = opts.domSettleTimeout;
-    this.disableAPI = (_g = opts.disableAPI) != null ? _g : false;
+    this.disableAPI = (_d2 = opts.disableAPI) != null ? _d2 : false;
     const baseClientOptions = clientOptions ? __spreadValues({}, clientOptions) : {};
     if (opts.llmClient) {
       this.llmClient = opts.llmClient;
@@ -63270,6 +64216,7 @@ var _V3 = class _V3 {
       act: this.act.bind(this)
     });
     this.opts = opts;
+    SessionFileLogger.init(this.instanceId, opts);
     _V3._instances.add(this);
   }
   get browserbaseSessionID() {
@@ -63571,6 +64518,9 @@ var _V3 = class _V3 {
               this.ctx = yield V3Context.create(lbo.cdpUrl, {
                 env: "LOCAL"
               });
+              const logCtx2 = SessionFileLogger.getContext();
+              this.ctx.conn.cdpLogger = (info) => SessionFileLogger.logCdpCallEvent(info, logCtx2);
+              this.ctx.conn.cdpEventLogger = (info) => SessionFileLogger.logCdpMessageEvent(info, logCtx2);
               this.ctx.conn.onTransportClosed(this._onCdpClosed);
               this.state = {
                 kind: "LOCAL",
@@ -63651,6 +64601,9 @@ var _V3 = class _V3 {
               env: "LOCAL",
               localBrowserLaunchOptions: lbo
             });
+            const logCtx = SessionFileLogger.getContext();
+            this.ctx.conn.cdpLogger = (info) => SessionFileLogger.logCdpCallEvent(info, logCtx);
+            this.ctx.conn.cdpEventLogger = (info) => SessionFileLogger.logCdpMessageEvent(info, logCtx);
             this.ctx.conn.onTransportClosed(this._onCdpClosed);
             this.state = {
               kind: "LOCAL",
@@ -63718,6 +64671,9 @@ var _V3 = class _V3 {
               env: "BROWSERBASE",
               apiClient: this.apiClient
             });
+            const logCtx = SessionFileLogger.getContext();
+            this.ctx.conn.cdpLogger = (info) => SessionFileLogger.logCdpCallEvent(info, logCtx);
+            this.ctx.conn.cdpEventLogger = (info) => SessionFileLogger.logCdpMessageEvent(info, logCtx);
             this.ctx.conn.onTransportClosed(this._onCdpClosed);
             this.state = { kind: "BROWSERBASE", sessionId, ws, bb };
             this.browserbaseSessionId = sessionId;
@@ -64020,6 +64976,10 @@ var _V3 = class _V3 {
       if (this._isClosing && !(opts == null ? void 0 : opts.force)) return;
       this._isClosing = true;
       try {
+        try {
+          yield SessionFileLogger.close();
+        } catch (e2) {
+        }
         try {
           if (((_a4 = this.ctx) == null ? void 0 : _a4.conn) && this._onCdpClosed) {
             (_c = (_b = this.ctx.conn).offTransportClosed) == null ? void 0 : _c.call(_b, this._onCdpClosed);
@@ -64105,7 +65065,7 @@ var _V3 = class _V3 {
         return frameTree.frame.id;
       }
       if (this.isPuppeteerPage(page)) {
-        const cdp = yield page.target().createCDPSession();
+        const cdp = yield page.createCDPSession();
         const { frameTree } = yield cdp.send("Page.getFrameTree");
         this.logger({
           category: "v3",
@@ -64278,6 +65238,10 @@ var _V3 = class _V3 {
         execute: (instructionOrOptions) => __async(this, null, function* () {
           return withInstanceLogContext(this.instanceId, () => __async(this, null, function* () {
             var _a5, _b2;
+            SessionFileLogger.logAgentTaskStarted({
+              invocation: "Agent.execute",
+              args: [instructionOrOptions]
+            });
             if ((options == null ? void 0 : options.integrations) && !this.experimental) {
               throw new ExperimentalNotConfiguredError("MCP integrations");
             }
@@ -64314,6 +65278,7 @@ Do not ask follow up questions, the user will trust your judgement.`
               if (cacheContext) {
                 const replayed = yield this.agentCache.tryReplay(cacheContext);
                 if (replayed) {
+                  SessionFileLogger.logAgentTaskCompleted({ cacheHit: true });
                   return replayed;
                 }
               }
@@ -64349,6 +65314,7 @@ Do not ask follow up questions, the user will trust your judgement.`
               if (recording) {
                 this.discardAgentReplayRecording();
               }
+              SessionFileLogger.logAgentTaskCompleted();
             }
           }));
         })
@@ -64359,6 +65325,10 @@ Do not ask follow up questions, the user will trust your judgement.`
     return {
       execute: (instructionOrOptions) => __async(this, null, function* () {
         return withInstanceLogContext(this.instanceId, () => __async(this, null, function* () {
+          SessionFileLogger.logAgentTaskStarted({
+            invocation: "Agent.execute",
+            args: [instructionOrOptions]
+          });
           if (typeof instructionOrOptions === "object" && instructionOrOptions.callbacks && !this.experimental) {
             throw new ExperimentalNotConfiguredError("Agent callbacks");
           }
@@ -64374,6 +65344,7 @@ Do not ask follow up questions, the user will trust your judgement.`
             if (cacheContext2) {
               const replayed = yield this.agentCache.tryReplayAsStream(cacheContext2);
               if (replayed) {
+                SessionFileLogger.logAgentTaskCompleted({ cacheHit: true });
                 return replayed;
               }
             }
@@ -64381,14 +65352,17 @@ Do not ask follow up questions, the user will trust your judgement.`
               instructionOrOptions
             );
             if (cacheContext2) {
-              return this.agentCache.wrapStreamForCaching(
+              const wrappedStream = this.agentCache.wrapStreamForCaching(
                 cacheContext2,
                 streamResult,
                 () => this.beginAgentReplayRecording(),
                 () => this.endAgentReplayRecording(),
                 () => this.discardAgentReplayRecording()
               );
+              SessionFileLogger.logAgentTaskCompleted();
+              return wrappedStream;
             }
+            SessionFileLogger.logAgentTaskCompleted();
             return streamResult;
           }
           const { handler, resolvedOptions, cacheContext } = yield this.prepareAgentExecution(
@@ -64399,6 +65373,7 @@ Do not ask follow up questions, the user will trust your judgement.`
           if (cacheContext) {
             const replayed = yield this.agentCache.tryReplay(cacheContext);
             if (replayed) {
+              SessionFileLogger.logAgentTaskCompleted({ cacheHit: true });
               return replayed;
             }
           }
@@ -64435,12 +65410,18 @@ Do not ask follow up questions, the user will trust your judgement.`
             if (recording) {
               this.discardAgentReplayRecording();
             }
+            SessionFileLogger.logAgentTaskCompleted();
           }
         }));
       })
     };
   }
 };
+_init2 = __decoratorStart(null);
+__decorateElement(_init2, 1, "act", _act_dec, _V3);
+__decorateElement(_init2, 1, "extract", _extract_dec, _V3);
+__decorateElement(_init2, 1, "observe", _observe_dec, _V3);
+__decoratorMetadata(_init2, _V3);
 _V3._processGuardsInstalled = false;
 _V3._instances = /* @__PURE__ */ new Set();
 var V3 = _V3;