@browserbasehq/orca 3.0.9-alpha-4 → 3.1.0-patch.1

package/dist/esm/lib/inferenceLogUtils.js

@@ -0,0 +1,92 @@
+import fs from "fs";
+import path from "path";
+/**
+ * Create (or ensure) a parent directory named "inference_summary".
+ */
+function ensureInferenceSummaryDir() {
+    const inferenceDir = path.join(process.cwd(), "inference_summary");
+    if (!fs.existsSync(inferenceDir)) {
+        fs.mkdirSync(inferenceDir, { recursive: true });
+    }
+    return inferenceDir;
+}
+/**
+ * Appends a new entry to the act_summary.json file, then writes the file back out.
+ */
+export function appendSummary(inferenceType, entry) {
+    const summaryPath = getSummaryJsonPath(inferenceType);
+    const arrayKey = `${inferenceType}_summary`;
+    const existingData = readSummaryFile(inferenceType);
+    existingData[arrayKey].push(entry);
+    fs.writeFileSync(summaryPath, JSON.stringify(existingData, null, 2));
+}
+/** A simple timestamp utility for filenames. */
+function getTimestamp() {
+    return new Date()
+        .toISOString()
+        .replace(/[^0-9T]/g, "")
+        .replace("T", "_");
+}
+/**
+ * Writes `data` as JSON into a file in `directory`, using a prefix plus timestamp.
+ * Returns both the file name and the timestamp used, so you can log them.
+ */
+export function writeTimestampedTxtFile(directory, prefix, data) {
+    const baseDir = ensureInferenceSummaryDir();
+    const subDir = path.join(baseDir, directory);
+    if (!fs.existsSync(subDir)) {
+        fs.mkdirSync(subDir, { recursive: true });
+    }
+    const timestamp = getTimestamp();
+    const fileName = `${timestamp}_${prefix}.txt`;
+    const filePath = path.join(subDir, fileName);
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2).replace(/\\n/g, "\n"));
+    return { fileName, timestamp };
+}
+/**
+ * Returns the path to the `<inferenceType>_summary.json` file.
+ *
+ * For example, if `inferenceType = "act"`, this will be:
+ *   `./inference_summary/act_summary/act_summary.json`
+ */
+function getSummaryJsonPath(inferenceType) {
+    const baseDir = ensureInferenceSummaryDir();
+    const subDir = path.join(baseDir, `${inferenceType}_summary`);
+    if (!fs.existsSync(subDir)) {
+        fs.mkdirSync(subDir, { recursive: true });
+    }
+    return path.join(subDir, `${inferenceType}_summary.json`);
+}
+/**
+ * Reads the `<inferenceType>_summary.json` file, returning an object
+ * with the top-level array named `<inferenceType>_summary`, if it exists.
+ *
+ * E.g. if inferenceType is "act", we expect a shape like:
+ * {
+ *   "act_summary": [ ... ]
+ * }
+ *
+ * If the file or array is missing, returns { "<inferenceType>_summary": [] }.
+ */
+function readSummaryFile(inferenceType) {
+    const summaryPath = getSummaryJsonPath(inferenceType);
+    // The top-level array key, e.g. "act_summary", "observe_summary", "extract_summary"
+    const arrayKey = `${inferenceType}_summary`;
+    if (!fs.existsSync(summaryPath)) {
+        return { [arrayKey]: [] };
+    }
+    try {
+        const raw = fs.readFileSync(summaryPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed &&
+            typeof parsed === "object" &&
+            Array.isArray(parsed[arrayKey])) {
+            return parsed;
+        }
+    }
+    catch {
+        // If we fail to parse for any reason, fall back to empty array
+    }
+    return { [arrayKey]: [] };
+}
+//# sourceMappingURL=inferenceLogUtils.js.map

package/dist/esm/lib/inferenceLogUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inferenceLogUtils.js","sourceRoot":"","sources":["../../../lib/inferenceLogUtils.ts"],"names":[],"mappings":"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","sourcesContent":["import fs from \"fs\";\nimport path from \"path\";\n\n/**\n * Create (or ensure) a parent directory named \"inference_summary\".\n */\nfunction ensureInferenceSummaryDir(): string {\n  const inferenceDir = path.join(process.cwd(), \"inference_summary\");\n  if (!fs.existsSync(inferenceDir)) {\n    fs.mkdirSync(inferenceDir, { recursive: true });\n  }\n  return inferenceDir;\n}\n\n/**\n * Appends a new entry to the act_summary.json file, then writes the file back out.\n */\nexport function appendSummary<T>(inferenceType: string, entry: T) {\n  const summaryPath = getSummaryJsonPath(inferenceType);\n  const arrayKey = `${inferenceType}_summary`;\n\n  const existingData = readSummaryFile<T>(inferenceType);\n  existingData[arrayKey].push(entry);\n\n  fs.writeFileSync(summaryPath, JSON.stringify(existingData, null, 2));\n}\n\n/** A simple timestamp utility for filenames. */\nfunction getTimestamp(): string {\n  return new Date()\n    .toISOString()\n    .replace(/[^0-9T]/g, \"\")\n    .replace(\"T\", \"_\");\n}\n\n/**\n * Writes `data` as JSON into a file in `directory`, using a prefix plus timestamp.\n * Returns both the file name and the timestamp used, so you can log them.\n */\nexport function writeTimestampedTxtFile(\n  directory: string,\n  prefix: string,\n  data: unknown,\n): { fileName: string; timestamp: string } {\n  const baseDir = ensureInferenceSummaryDir();\n\n  const subDir = path.join(baseDir, directory);\n  if (!fs.existsSync(subDir)) {\n    fs.mkdirSync(subDir, { recursive: true });\n  }\n\n  const timestamp = getTimestamp();\n  const fileName = `${timestamp}_${prefix}.txt`;\n  const filePath = path.join(subDir, fileName);\n\n  fs.writeFileSync(\n    filePath,\n    JSON.stringify(data, null, 2).replace(/\\\\n/g, \"\\n\"),\n  );\n\n  return { fileName, timestamp };\n}\n\n/**\n * Returns the path to the `<inferenceType>_summary.json` file.\n *\n * For example, if `inferenceType = \"act\"`, this will be:\n *   `./inference_summary/act_summary/act_summary.json`\n */\nfunction getSummaryJsonPath(inferenceType: string): string {\n  const baseDir = ensureInferenceSummaryDir();\n  const subDir = path.join(baseDir, `${inferenceType}_summary`);\n  if (!fs.existsSync(subDir)) {\n    fs.mkdirSync(subDir, { recursive: true });\n  }\n  return path.join(subDir, `${inferenceType}_summary.json`);\n}\n\n/**\n * Reads the `<inferenceType>_summary.json` file, returning an object\n * with the top-level array named `<inferenceType>_summary`, if it exists.\n *\n * E.g. if inferenceType is \"act\", we expect a shape like:\n * {\n *   \"act_summary\": [ ... ]\n * }\n *\n * If the file or array is missing, returns { \"<inferenceType>_summary\": [] }.\n */\nfunction readSummaryFile<T>(inferenceType: string): Record<string, T[]> {\n  const summaryPath = getSummaryJsonPath(inferenceType);\n\n  // The top-level array key, e.g. \"act_summary\", \"observe_summary\", \"extract_summary\"\n  const arrayKey = `${inferenceType}_summary`;\n\n  if (!fs.existsSync(summaryPath)) {\n    return { [arrayKey]: [] };\n  }\n\n  try {\n    const raw = fs.readFileSync(summaryPath, \"utf8\");\n    const parsed = JSON.parse(raw);\n    if (\n      parsed &&\n      typeof parsed === \"object\" &&\n      Array.isArray(parsed[arrayKey])\n    ) {\n      return parsed;\n    }\n  } catch {\n    // If we fail to parse for any reason, fall back to empty array\n  }\n  return { [arrayKey]: [] };\n}\n"]}

package/dist/esm/lib/logger.d.ts

@@ -0,0 +1,69 @@
+import pino from "pino";
+import { LogLine } from "./v3/types/public/logs.js";
+export interface LoggerOptions {
+    pretty?: boolean;
+    level?: pino.Level;
+    destination?: pino.DestinationStream;
+    usePino?: boolean;
+}
+/**
+ * Creates a configured Pino logger instance
+ */
+export declare function createLogger(options?: LoggerOptions): import("pino").Logger<never, boolean>;
+/**
+ * StagehandLogger class that wraps Pino for our specific needs
+ *
+ * LOGGING PRECEDENCE:
+ *
+ * Test environments:
+ *   - External logger provided -> external logger only.
+ *   - No external logger -> console fallback only (Pino disabled).
+ *
+ * Non-test environments:
+ *   - usePino === true -> emit via Pino and also call the external logger when present.
+ *   - usePino === false -> disable Pino; use the external logger when present, otherwise console fallback.
+ *   - usePino === undefined -> prefer the external logger when present; otherwise use Pino.
+ *
+ * SHARED PINO OPTIMIZATION:
+ * We maintain a single shared Pino instance when `usePino` is enabled.
+ * This prevents spawning a new worker thread for every Stagehand instance
+ * (which happens when `pino-pretty` transport is used), eliminating the
+ * memory/RSS growth observed when many Stagehand objects are created and
+ * disposed within the same process (e.g. a request-per-instance API).
+ */
+export declare class StagehandLogger {
+    /**
+     * Shared Pino logger instance across all StagehandLogger instances.
+     * First instance to enable Pino creates it, subsequent instances reuse it.
+     */
+    private static sharedPinoLogger;
+    private logger?;
+    private verbose;
+    private externalLogger?;
+    private usePino;
+    private isTest;
+    constructor(options?: LoggerOptions, externalLogger?: (logLine: LogLine) => void);
+    /**
+     * Set the verbosity level
+     */
+    setVerbosity(level: 0 | 1 | 2): void;
+    /**
+     * Log a message using our LogLine format
+     */
+    log(logLine: LogLine): void;
+    /**
+     * Helper to format auxiliary data for structured logging
+     */
+    private formatAuxiliaryData;
+    /**
+     * Convenience methods for different log levels
+     */
+    error(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    debug(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Convert a plain object to our auxiliary format
+     */
+    private convertToAuxiliary;
+}

package/dist/esm/lib/logger.js

@@ -0,0 +1,323 @@
+import pino from "pino";
+// Map our existing levels to Pino's standard levels
+const levelMapping = {
+    0: "error", // Critical/important messages
+    1: "info", // Standard information
+    2: "debug", // Detailed debugging information
+};
+/**
+ * Creates a configured Pino logger instance
+ */
+export function createLogger(options = {}) {
+    const loggerConfig = {
+        level: options.level || "info",
+        base: undefined, // Don't include pid and hostname
+        browser: {
+            asObject: true,
+        },
+        // Disable worker threads to avoid issues in tests
+        transport: undefined,
+    };
+    // Add pretty printing for dev environments only if explicitly requested
+    // and not in a test environment
+    if (options.pretty && !isTestEnvironment()) {
+        try {
+            // Use require for dynamic import
+            const transport = {
+                transport: {
+                    target: "pino-pretty",
+                    options: {
+                        colorize: true,
+                        translateTime: "SYS:standard",
+                        ignore: "pid,hostname",
+                    },
+                },
+            };
+            Object.assign(loggerConfig, transport);
+        }
+        catch {
+            console.warn("pino-pretty not available, falling back to standard logging");
+        }
+    }
+    return pino(loggerConfig, options.destination);
+}
+/**
+ * Check if we're running in a test environment
+ */
+function isTestEnvironment() {
+    return (process.env.NODE_ENV === "test" ||
+        process.env.JEST_WORKER_ID !== undefined ||
+        process.env.PLAYWRIGHT_TEST_BASE_DIR !== undefined ||
+        // Check if we're in a CI environment
+        process.env.CI === "true");
+}
+/**
+ * StagehandLogger class that wraps Pino for our specific needs
+ *
+ * LOGGING PRECEDENCE:
+ *
+ * Test environments:
+ *   - External logger provided -> external logger only.
+ *   - No external logger -> console fallback only (Pino disabled).
+ *
+ * Non-test environments:
+ *   - usePino === true -> emit via Pino and also call the external logger when present.
+ *   - usePino === false -> disable Pino; use the external logger when present, otherwise console fallback.
+ *   - usePino === undefined -> prefer the external logger when present; otherwise use Pino.
+ *
+ * SHARED PINO OPTIMIZATION:
+ * We maintain a single shared Pino instance when `usePino` is enabled.
+ * This prevents spawning a new worker thread for every Stagehand instance
+ * (which happens when `pino-pretty` transport is used), eliminating the
+ * memory/RSS growth observed when many Stagehand objects are created and
+ * disposed within the same process (e.g. a request-per-instance API).
+ */
+export class StagehandLogger {
+    /**
+     * Shared Pino logger instance across all StagehandLogger instances.
+     * First instance to enable Pino creates it, subsequent instances reuse it.
+     */
+    static sharedPinoLogger = null;
+    logger;
+    verbose;
+    externalLogger;
+    usePino;
+    isTest;
+    constructor(options = {}, externalLogger) {
+        this.isTest = isTestEnvironment();
+        this.externalLogger = externalLogger;
+        const externalProvided = typeof externalLogger === "function";
+        const explicitUsePino = options.usePino;
+        if (this.isTest) {
+            this.usePino = false;
+        }
+        else if (explicitUsePino === true) {
+            this.usePino = true;
+        }
+        else if (explicitUsePino === false) {
+            this.usePino = false;
+        }
+        else {
+            this.usePino = !externalProvided;
+        }
+        if (this.usePino) {
+            // Re-use (or create) a single shared Pino logger instance
+            if (!StagehandLogger.sharedPinoLogger) {
+                StagehandLogger.sharedPinoLogger = createLogger(options);
+            }
+            this.logger = StagehandLogger.sharedPinoLogger;
+        }
+        this.verbose = 1; // Default verbosity level
+    }
+    /**
+     * Set the verbosity level
+     */
+    setVerbosity(level) {
+        this.verbose = level;
+        if (this.usePino && this.logger) {
+            // Map our verbosity levels to Pino log levels
+            switch (level) {
+                case 0:
+                    this.logger.level = "error";
+                    break;
+                case 1:
+                    this.logger.level = "info";
+                    break;
+                case 2:
+                    this.logger.level = "debug";
+                    break;
+            }
+        }
+    }
+    /**
+     * Log a message using our LogLine format
+     */
+    log(logLine) {
+        // Skip logs above verbosity level
+        if ((logLine.level ?? 1) > this.verbose) {
+            return;
+        }
+        // For test environments WITHOUT an external logger OR for cases where Pino
+        // is disabled and no external logger is provided, fall back to console.* so
+        // users still see logs (non-colourised).
+        const shouldFallbackToConsole = (!this.usePino && !this.externalLogger) ||
+            (this.isTest && !this.externalLogger);
+        if (shouldFallbackToConsole) {
+            const level = logLine.level ?? 1;
+            const ts = logLine.timestamp ?? new Date().toISOString();
+            const levelStr = level === 0 ? "ERROR" : level === 2 ? "DEBUG" : "INFO";
+            // Format like Pino: [timestamp] LEVEL: message
+            let output = `[${ts}] ${levelStr}: ${logLine.message}`;
+            // Add auxiliary data on separate indented lines (like Pino pretty format)
+            if (logLine.auxiliary) {
+                const formattedData = this.formatAuxiliaryData(logLine.auxiliary);
+                for (const [key, value] of Object.entries(formattedData)) {
+                    let formattedValue;
+                    if (typeof value === "object" && value !== null) {
+                        // Pretty print objects with indentation
+                        formattedValue = JSON.stringify(value, null, 2)
+                            .split("\n")
+                            .map((line, i) => (i === 0 ? line : `    ${line}`))
+                            .join("\n");
+                    }
+                    else {
+                        formattedValue = String(value);
+                    }
+                    output += `\n    ${key}: ${formattedValue}`;
+                }
+            }
+            switch (level) {
+                case 0:
+                    console.error(output);
+                    break;
+                case 1:
+                    console.log(output);
+                    break;
+                case 2:
+                    console.debug(output);
+                    break;
+            }
+            return; // already handled via console output, avoid duplicate logging
+        }
+        if (this.usePino && this.logger) {
+            // Determine the Pino log level
+            const pinoLevel = levelMapping[logLine.level ?? 1] || "info";
+            // Structure the log data
+            const logData = {
+                category: logLine.category,
+                timestamp: logLine.timestamp || new Date().toISOString(),
+                ...this.formatAuxiliaryData(logLine.auxiliary),
+            };
+            // Log through Pino with the appropriate level
+            if (pinoLevel === "error") {
+                this.logger.error(logData, logLine.message);
+            }
+            else if (pinoLevel === "info") {
+                this.logger.info(logData, logLine.message);
+            }
+            else if (pinoLevel === "debug") {
+                this.logger.debug(logData, logLine.message);
+            }
+            else if (pinoLevel === "warn") {
+                this.logger.warn(logData, logLine.message);
+            }
+            else if (pinoLevel === "trace") {
+                this.logger.trace(logData, logLine.message);
+            }
+            else {
+                this.logger.info(logData, logLine.message);
+            }
+        }
+        // IMPORTANT: External logger receives logs ALWAYS when provided (takes precedence)
+        // This ensures user-provided loggers (e.g., EvalLogger, custom loggers) capture all logs
+        // regardless of Pino configuration. Pino is used for console output, external logger
+        // is used for programmatic log capture.
+        if (this.externalLogger) {
+            this.externalLogger(logLine);
+        }
+    }
+    /**
+     * Helper to format auxiliary data for structured logging
+     */
+    formatAuxiliaryData(auxiliary) {
+        if (!auxiliary)
+            return {};
+        const formattedData = {};
+        for (const [key, { value, type }] of Object.entries(auxiliary)) {
+            let formattedValue;
+            // Convert values based on their type
+            switch (type) {
+                case "integer":
+                    formattedValue = parseInt(value, 10);
+                    break;
+                case "float":
+                    formattedValue = parseFloat(value);
+                    break;
+                case "boolean":
+                    formattedValue = value === "true";
+                    break;
+                case "object":
+                    try {
+                        formattedValue = JSON.parse(value);
+                    }
+                    catch {
+                        formattedValue = value;
+                    }
+                    break;
+                default:
+                    formattedValue = value;
+            }
+            // Skip undefined values and empty objects/arrays
+            if (formattedValue === undefined)
+                continue;
+            if (typeof formattedValue === "object" && formattedValue !== null) {
+                const isEmpty = Array.isArray(formattedValue)
+                    ? formattedValue.length === 0
+                    : Object.keys(formattedValue).length === 0;
+                if (isEmpty)
+                    continue;
+            }
+            formattedData[key] = formattedValue;
+        }
+        return formattedData;
+    }
+    /**
+     * Convenience methods for different log levels
+     */
+    error(message, data) {
+        this.log({
+            message,
+            level: 0,
+            auxiliary: this.convertToAuxiliary(data),
+        });
+    }
+    warn(message, data) {
+        this.log({
+            message,
+            level: 1,
+            category: "warning",
+            auxiliary: this.convertToAuxiliary(data),
+        });
+    }
+    info(message, data) {
+        this.log({
+            message,
+            level: 1,
+            auxiliary: this.convertToAuxiliary(data),
+        });
+    }
+    debug(message, data) {
+        this.log({
+            message,
+            level: 2,
+            auxiliary: this.convertToAuxiliary(data),
+        });
+    }
+    /**
+     * Convert a plain object to our auxiliary format
+     */
+    convertToAuxiliary(data) {
+        if (!data)
+            return undefined;
+        const auxiliary = {};
+        for (const [key, value] of Object.entries(data)) {
+            if (value === undefined)
+                continue;
+            const type = typeof value;
+            auxiliary[key] = {
+                value: type === "object" ? JSON.stringify(value) : String(value),
+                type: type === "number"
+                    ? Number.isInteger(value)
+                        ? "integer"
+                        : "float"
+                    : type === "boolean"
+                        ? "boolean"
+                        : type === "object"
+                            ? "object"
+                            : "string",
+            };
+        }
+        return auxiliary;
+    }
+}
+//# sourceMappingURL=logger.js.map

package/dist/esm/lib/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../../lib/logger.ts"],"names":[],"mappings":"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","sourcesContent":["import pino from \"pino\";\nimport { LogLine } from \"./v3/types/public/logs.js\";\n\n// Map our existing levels to Pino's standard levels\nconst levelMapping: Record<number, pino.Level> = {\n  0: \"error\", // Critical/important messages\n  1: \"info\", // Standard information\n  2: \"debug\", // Detailed debugging information\n};\n\n// Define configuration options\nexport interface LoggerOptions {\n  pretty?: boolean;\n  level?: pino.Level;\n  destination?: pino.DestinationStream;\n  usePino?: boolean; // Whether to use pino (default: true)\n}\n\n/**\n * Creates a configured Pino logger instance\n */\nexport function createLogger(options: LoggerOptions = {}) {\n  const loggerConfig: pino.LoggerOptions = {\n    level: options.level || \"info\",\n    base: undefined, // Don't include pid and hostname\n    browser: {\n      asObject: true,\n    },\n    // Disable worker threads to avoid issues in tests\n    transport: undefined,\n  };\n\n  // Add pretty printing for dev environments only if explicitly requested\n  // and not in a test environment\n  if (options.pretty && !isTestEnvironment()) {\n    try {\n      // Use require for dynamic import\n      const transport = {\n        transport: {\n          target: \"pino-pretty\",\n          options: {\n            colorize: true,\n            translateTime: \"SYS:standard\",\n            ignore: \"pid,hostname\",\n          },\n        },\n      };\n      Object.assign(loggerConfig, transport);\n    } catch {\n      console.warn(\n        \"pino-pretty not available, falling back to standard logging\",\n      );\n    }\n  }\n\n  return pino(loggerConfig, options.destination);\n}\n\n/**\n * Check if we're running in a test environment\n */\nfunction isTestEnvironment(): boolean {\n  return (\n    process.env.NODE_ENV === \"test\" ||\n    process.env.JEST_WORKER_ID !== undefined ||\n    process.env.PLAYWRIGHT_TEST_BASE_DIR !== undefined ||\n    // Check if we're in a CI environment\n    process.env.CI === \"true\"\n  );\n}\n\n/**\n * StagehandLogger class that wraps Pino for our specific needs\n *\n * LOGGING PRECEDENCE:\n *\n * Test environments:\n *   - External logger provided -> external logger only.\n *   - No external logger -> console fallback only (Pino disabled).\n *\n * Non-test environments:\n *   - usePino === true -> emit via Pino and also call the external logger when present.\n *   - usePino === false -> disable Pino; use the external logger when present, otherwise console fallback.\n *   - usePino === undefined -> prefer the external logger when present; otherwise use Pino.\n *\n * SHARED PINO OPTIMIZATION:\n * We maintain a single shared Pino instance when `usePino` is enabled.\n * This prevents spawning a new worker thread for every Stagehand instance\n * (which happens when `pino-pretty` transport is used), eliminating the\n * memory/RSS growth observed when many Stagehand objects are created and\n * disposed within the same process (e.g. a request-per-instance API).\n */\nexport class StagehandLogger {\n  /**\n   * Shared Pino logger instance across all StagehandLogger instances.\n   * First instance to enable Pino creates it, subsequent instances reuse it.\n   */\n  private static sharedPinoLogger: pino.Logger | null = null;\n\n  private logger?: pino.Logger;\n  private verbose: 0 | 1 | 2;\n  private externalLogger?: (logLine: LogLine) => void;\n  private usePino: boolean;\n  private isTest: boolean;\n\n  constructor(\n    options: LoggerOptions = {},\n    externalLogger?: (logLine: LogLine) => void,\n  ) {\n    this.isTest = isTestEnvironment();\n    this.externalLogger = externalLogger;\n\n    const externalProvided = typeof externalLogger === \"function\";\n    const explicitUsePino = options.usePino;\n\n    if (this.isTest) {\n      this.usePino = false;\n    } else if (explicitUsePino === true) {\n      this.usePino = true;\n    } else if (explicitUsePino === false) {\n      this.usePino = false;\n    } else {\n      this.usePino = !externalProvided;\n    }\n\n    if (this.usePino) {\n      // Re-use (or create) a single shared Pino logger instance\n      if (!StagehandLogger.sharedPinoLogger) {\n        StagehandLogger.sharedPinoLogger = createLogger(options);\n      }\n      this.logger = StagehandLogger.sharedPinoLogger;\n    }\n\n    this.verbose = 1; // Default verbosity level\n  }\n\n  /**\n   * Set the verbosity level\n   */\n  setVerbosity(level: 0 | 1 | 2) {\n    this.verbose = level;\n\n    if (this.usePino && this.logger) {\n      // Map our verbosity levels to Pino log levels\n      switch (level) {\n        case 0:\n          this.logger.level = \"error\";\n          break;\n        case 1:\n          this.logger.level = \"info\";\n          break;\n        case 2:\n          this.logger.level = \"debug\";\n          break;\n      }\n    }\n  }\n\n  /**\n   * Log a message using our LogLine format\n   */\n  log(logLine: LogLine): void {\n    // Skip logs above verbosity level\n    if ((logLine.level ?? 1) > this.verbose) {\n      return;\n    }\n\n    // For test environments WITHOUT an external logger OR for cases where Pino\n    // is disabled and no external logger is provided, fall back to console.* so\n    // users still see logs (non-colourised).\n    const shouldFallbackToConsole =\n      (!this.usePino && !this.externalLogger) ||\n      (this.isTest && !this.externalLogger);\n\n    if (shouldFallbackToConsole) {\n      const level = logLine.level ?? 1;\n      const ts = logLine.timestamp ?? new Date().toISOString();\n      const levelStr = level === 0 ? \"ERROR\" : level === 2 ? \"DEBUG\" : \"INFO\";\n\n      // Format like Pino: [timestamp] LEVEL: message\n      let output = `[${ts}] ${levelStr}: ${logLine.message}`;\n\n      // Add auxiliary data on separate indented lines (like Pino pretty format)\n      if (logLine.auxiliary) {\n        const formattedData = this.formatAuxiliaryData(logLine.auxiliary);\n        for (const [key, value] of Object.entries(formattedData)) {\n          let formattedValue: string;\n          if (typeof value === \"object\" && value !== null) {\n            // Pretty print objects with indentation\n            formattedValue = JSON.stringify(value, null, 2)\n              .split(\"\\n\")\n              .map((line, i) => (i === 0 ? line : `    ${line}`))\n              .join(\"\\n\");\n          } else {\n            formattedValue = String(value);\n          }\n          output += `\\n    ${key}: ${formattedValue}`;\n        }\n      }\n\n      switch (level) {\n        case 0:\n          console.error(output);\n          break;\n        case 1:\n          console.log(output);\n          break;\n        case 2:\n          console.debug(output);\n          break;\n      }\n\n      return; // already handled via console output, avoid duplicate logging\n    }\n\n    if (this.usePino && this.logger) {\n      // Determine the Pino log level\n      const pinoLevel = levelMapping[logLine.level ?? 1] || \"info\";\n\n      // Structure the log data\n      const logData = {\n        category: logLine.category,\n        timestamp: logLine.timestamp || new Date().toISOString(),\n        ...this.formatAuxiliaryData(logLine.auxiliary),\n      };\n\n      // Log through Pino with the appropriate level\n      if (pinoLevel === \"error\") {\n        this.logger.error(logData, logLine.message);\n      } else if (pinoLevel === \"info\") {\n        this.logger.info(logData, logLine.message);\n      } else if (pinoLevel === \"debug\") {\n        this.logger.debug(logData, logLine.message);\n      } else if (pinoLevel === \"warn\") {\n        this.logger.warn(logData, logLine.message);\n      } else if (pinoLevel === \"trace\") {\n        this.logger.trace(logData, logLine.message);\n      } else {\n        this.logger.info(logData, logLine.message);\n      }\n    }\n\n    // IMPORTANT: External logger receives logs ALWAYS when provided (takes precedence)\n    // This ensures user-provided loggers (e.g., EvalLogger, custom loggers) capture all logs\n    // regardless of Pino configuration. Pino is used for console output, external logger\n    // is used for programmatic log capture.\n    if (this.externalLogger) {\n      this.externalLogger(logLine);\n    }\n  }\n\n  /**\n   * Helper to format auxiliary data for structured logging\n   */\n  private formatAuxiliaryData(auxiliary?: LogLine[\"auxiliary\"]) {\n    if (!auxiliary) return {};\n\n    const formattedData: Record<string, unknown> = {};\n\n    for (const [key, { value, type }] of Object.entries(auxiliary)) {\n      let formattedValue: unknown;\n\n      // Convert values based on their type\n      switch (type) {\n        case \"integer\":\n          formattedValue = parseInt(value, 10);\n          break;\n        case \"float\":\n          formattedValue = parseFloat(value);\n          break;\n        case \"boolean\":\n          formattedValue = value === \"true\";\n          break;\n        case \"object\":\n          try {\n            formattedValue = JSON.parse(value);\n          } catch {\n            formattedValue = value;\n          }\n          break;\n        default:\n          formattedValue = value;\n      }\n\n      // Skip undefined values and empty objects/arrays\n      if (formattedValue === undefined) continue;\n      if (typeof formattedValue === \"object\" && formattedValue !== null) {\n        const isEmpty = Array.isArray(formattedValue)\n          ? formattedValue.length === 0\n          : Object.keys(formattedValue).length === 0;\n        if (isEmpty) continue;\n      }\n\n      formattedData[key] = formattedValue;\n    }\n\n    return formattedData;\n  }\n\n  /**\n   * Convenience methods for different log levels\n   */\n  error(message: string, data?: Record<string, unknown>): void {\n    this.log({\n      message,\n      level: 0,\n      auxiliary: this.convertToAuxiliary(data),\n    });\n  }\n\n  warn(message: string, data?: Record<string, unknown>): void {\n    this.log({\n      message,\n      level: 1,\n      category: \"warning\",\n      auxiliary: this.convertToAuxiliary(data),\n    });\n  }\n\n  info(message: string, data?: Record<string, unknown>): void {\n    this.log({\n      message,\n      level: 1,\n      auxiliary: this.convertToAuxiliary(data),\n    });\n  }\n\n  debug(message: string, data?: Record<string, unknown>): void {\n    this.log({\n      message,\n      level: 2,\n      auxiliary: this.convertToAuxiliary(data),\n    });\n  }\n\n  /**\n   * Convert a plain object to our auxiliary format\n   */\n  private convertToAuxiliary(\n    data?: Record<string, unknown>,\n  ): LogLine[\"auxiliary\"] {\n    if (!data) return undefined;\n\n    const auxiliary: LogLine[\"auxiliary\"] = {};\n\n    for (const [key, value] of Object.entries(data)) {\n      if (value === undefined) continue;\n\n      const type = typeof value;\n\n      auxiliary[key] = {\n        value: type === \"object\" ? JSON.stringify(value) : String(value),\n        type:\n          type === \"number\"\n            ? Number.isInteger(value)\n              ? \"integer\"\n              : \"float\"\n            : type === \"boolean\"\n              ? \"boolean\"\n              : type === \"object\"\n                ? \"object\"\n                : \"string\",\n      };\n    }\n\n    return auxiliary;\n  }\n}\n"]}

package/dist/esm/lib/modelUtils.d.ts

@@ -0,0 +1,11 @@
+import { ClientOptions, ModelConfiguration } from "./v3/types/public/model.js";
+export declare function splitModelName(model: string): {
+    provider: string;
+    modelName: string;
+};
+export declare function resolveModel(model: string | ModelConfiguration): {
+    provider: string;
+    modelName: string;
+    clientOptions: ClientOptions;
+    isCua: boolean;
+};

package/dist/esm/lib/modelUtils.js

@@ -0,0 +1,43 @@
+import { AVAILABLE_CUA_MODELS, } from "./v3/types/public/agent.js";
+export function splitModelName(model) {
+    const firstSlashIndex = model.indexOf("/");
+    const provider = model.substring(0, firstSlashIndex);
+    const modelName = model.substring(firstSlashIndex + 1);
+    return { provider, modelName };
+}
+export function resolveModel(model) {
+    // Extract the model string and client options
+    const modelString = typeof model === "string" ? model : model.modelName;
+    const clientOptions = typeof model === "string"
+        ? {}
+        : (() => {
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { modelName: _, ...rest } = model;
+            return rest;
+        })();
+    // Check if provider is explicitly set in clientOptions
+    const hasExplicitProvider = clientOptions.provider !== undefined;
+    // If provider is explicitly set, don't split the model name - pass it through as-is
+    let provider;
+    let parsedModelName;
+    if (hasExplicitProvider) {
+        provider = clientOptions.provider;
+        parsedModelName = modelString; // Keep the full model name
+    }
+    else {
+        // Parse the model string normally
+        const split = splitModelName(modelString);
+        provider = split.provider;
+        parsedModelName = split.modelName;
+    }
+    // Check if it's a CUA model
+    const isCua = hasExplicitProvider ||
+        AVAILABLE_CUA_MODELS.includes(modelString);
+    return {
+        provider,
+        modelName: parsedModelName,
+        clientOptions,
+        isCua,
+    };
+}
+//# sourceMappingURL=modelUtils.js.map

package/dist/esm/lib/modelUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"modelUtils.js","sourceRoot":"","sources":["../../../lib/modelUtils.ts"],"names":[],"mappings":"AACA,OAAO,EACL,oBAAoB,GAErB,MAAM,4BAA4B,CAAC;AAEpC,MAAM,UAAU,cAAc,CAAC,KAAa;IAI1C,MAAM,eAAe,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3C,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;IACrD,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC,eAAe,GAAG,CAAC,CAAC,CAAC;IACvD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAkC;IAM7D,8CAA8C;IAC9C,MAAM,WAAW,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC;IACxE,MAAM,aAAa,GACjB,OAAO,KAAK,KAAK,QAAQ;QACvB,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,CAAC,GAAG,EAAE;YACJ,6DAA6D;YAC7D,MAAM,EAAE,SAAS,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC;YACxC,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,EAAE,CAAC;IAEX,uDAAuD;IACvD,MAAM,mBAAmB,GAAG,aAAa,CAAC,QAAQ,KAAK,SAAS,CAAC;IAEjE,oFAAoF;IACpF,IAAI,QAAgB,CAAC;IACrB,IAAI,eAAuB,CAAC;IAE5B,IAAI,mBAAmB,EAAE,CAAC;QACxB,QAAQ,GAAG,aAAa,CAAC,QAAkB,CAAC;QAC5C,eAAe,GAAG,WAAW,CAAC,CAAC,2BAA2B;IAC5D,CAAC;SAAM,CAAC;QACN,kCAAkC;QAClC,MAAM,KAAK,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC;QAC1C,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QAC1B,eAAe,GAAG,KAAK,CAAC,SAAS,CAAC;IACpC,CAAC;IAED,4BAA4B;IAC5B,MAAM,KAAK,GACT,mBAAmB;QACnB,oBAAoB,CAAC,QAAQ,CAAC,WAAgC,CAAC,CAAC;IAElE,OAAO;QACL,QAAQ;QACR,SAAS,EAAE,eAAe;QAC1B,aAAa;QACb,KAAK;KACN,CAAC;AACJ,CAAC","sourcesContent":["import { ClientOptions, ModelConfiguration } from \"./v3/types/public/model.js\";\nimport {\n  AVAILABLE_CUA_MODELS,\n  AvailableCuaModel,\n} from \"./v3/types/public/agent.js\";\n\nexport function splitModelName(model: string): {\n  provider: string;\n  modelName: string;\n} {\n  const firstSlashIndex = model.indexOf(\"/\");\n  const provider = model.substring(0, firstSlashIndex);\n  const modelName = model.substring(firstSlashIndex + 1);\n  return { provider, modelName };\n}\n\nexport function resolveModel(model: string | ModelConfiguration): {\n  provider: string;\n  modelName: string;\n  clientOptions: ClientOptions;\n  isCua: boolean;\n} {\n  // Extract the model string and client options\n  const modelString = typeof model === \"string\" ? model : model.modelName;\n  const clientOptions =\n    typeof model === \"string\"\n      ? {}\n      : (() => {\n          // eslint-disable-next-line @typescript-eslint/no-unused-vars\n          const { modelName: _, ...rest } = model;\n          return rest;\n        })();\n\n  // Check if provider is explicitly set in clientOptions\n  const hasExplicitProvider = clientOptions.provider !== undefined;\n\n  // If provider is explicitly set, don't split the model name - pass it through as-is\n  let provider: string;\n  let parsedModelName: string;\n\n  if (hasExplicitProvider) {\n    provider = clientOptions.provider as string;\n    parsedModelName = modelString; // Keep the full model name\n  } else {\n    // Parse the model string normally\n    const split = splitModelName(modelString);\n    provider = split.provider;\n    parsedModelName = split.modelName;\n  }\n\n  // Check if it's a CUA model\n  const isCua =\n    hasExplicitProvider ||\n    AVAILABLE_CUA_MODELS.includes(modelString as AvailableCuaModel);\n\n  return {\n    provider,\n    modelName: parsedModelName,\n    clientOptions,\n    isCua,\n  };\n}\n"]}

package/dist/esm/lib/prompt.d.ts

@@ -0,0 +1,14 @@
+import { ChatMessage } from "./v3/llm/LLMClient.js";
+export declare function buildUserInstructionsString(userProvidedInstructions?: string): string;
+export declare function buildExtractSystemPrompt(isUsingPrintExtractedDataTool?: boolean, userProvidedInstructions?: string): ChatMessage;
+export declare function buildExtractUserPrompt(instruction: string, domElements: string, isUsingPrintExtractedDataTool?: boolean): ChatMessage;
+export declare function buildMetadataSystemPrompt(): ChatMessage;
+export declare function buildMetadataPrompt(instruction: string, extractionResponse: object): ChatMessage;
+export declare function buildObserveSystemPrompt(userProvidedInstructions?: string, supportedActions?: string[]): ChatMessage;
+export declare function buildObserveUserMessage(instruction: string, domElements: string): ChatMessage;
+export declare function buildActSystemPrompt(userProvidedInstructions?: string): ChatMessage;
+export declare function buildActPrompt(action: string, supportedActions: string[], variables?: Record<string, string>): string;
+export declare function buildStepTwoPrompt(originalUserAction: string, previousAction: string, supportedActions: string[], variables?: Record<string, string>): string;
+export declare function buildOperatorSystemPrompt(goal: string): ChatMessage;
+export declare function buildCuaDefaultSystemPrompt(): string;
+export declare function buildGoogleCUASystemPrompt(): ChatMessage;