effective logger

[filip-michalsky]

Why

Improved logging consistency and debuggability across the Stagehand codebase (STG-907). The codebase had inconsistent logging practices with many console.log, console.error, and console.warn calls that weren't properly integrated with Stagehand's logging system. Additionally, several silent error catches made debugging difficult.

What Changed

Agent Clients (Anthropic, Google, OpenAI CUA)

• Updated captureScreenshot() signature to accept logger parameter across all agent clients
• Replaced all console.error() and console.warn() calls with proper structured logger() calls
• Enhanced error logging with proper auxiliary data including error messages, stack traces, and context
• Updated getAction(), convertToolUseToAction(), and convertFunctionCallToAction() to accept and use logger parameter

Error Handling Improvements

• inferenceLogUtils.ts: Changed silent catch to log parse failures with error details
• consoleMessage.ts: Added logging for JSON stringify failures
• selectorResolver.ts: Added detailed error logging for:
  • Failed CSS selector counts (packages/core/lib/v3/understudy/selectorResolver.ts:331)
  • Failed XPath counts (packages/core/lib/v3/understudy/selectorResolver.ts:370)
  • Node resolution failures (packages/core/lib/v3/understudy/selectorResolver.ts:386)
  • Count/element expression evaluation failures (packages/core/lib/v3/understudy/selectorResolver.ts:418, :445)

Debugging Improvements

• piercer.runtime.ts: Removed hardcoded DEBUG = true, now respects opts.debug parameter (defaults to false)
• googleCustomToolHandler.ts: Removed console.error in tool conversion (silent fail is acceptable here)

AI SDK Client

• Added logger parameter to createChatCompletion() to allow caller-specific loggers
• Uses passed logger or falls back to instance logger

Eval Tasks

• Replaced console.log() calls with structured logger.log() in:
  • github_react_version.ts
  • hugging_face.ts
  • amazon_add_to_cart.ts
  • index.eval.ts

Test Plan

• Build passes (pnpm run build)
• Linting passes (pnpm run lint)
• Test in CI pass

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: 6b536ff6fd7f292cc902acd85042bd840ccbb5fe

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[greptile-apps[bot]]

Greptile Overview

Greptile Summary

This PR systematically replaces inconsistent logging practices (console.log, console.error, console.warn) with structured logger calls throughout the Stagehand codebase.

Key Changes

• Agent clients: Updated AnthropicCUAClient, GoogleCUAClient, and OpenAICUAClient to thread logger parameters through getAction(), convertToolUseToAction(), convertFunctionCallToAction(), and captureScreenshot() methods
• Error handling: Replaced silent catch blocks with detailed error logging in selectorResolver.ts (CSS/XPath failures), consoleMessage.ts (JSON stringify failures), and inferenceLogUtils.ts (parse failures)
• Debug improvements: Fixed piercer.runtime.ts to respect opts.debug parameter instead of hardcoded DEBUG = true
• AI SDK: Added optional logger parameter to createChatCompletion() with fallback to instance logger
• Eval tasks: Replaced console.log calls with structured logger.log() in evaluation scripts

All error logs now include structured auxiliary data with error messages, stack traces, and relevant context for better debuggability.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The changes are purely logging improvements that enhance debuggability without altering business logic. All modifications follow consistent patterns: replacing console methods with structured logger calls and threading logger parameters through method signatures. The PR maintains backward compatibility (aisdk logger fallback), removes problematic hardcoded debug flags, and builds/lints successfully.
• No files require special attention

Important Files Changed

File Analysis

Filename	Score	Overview
packages/core/lib/v3/agent/AnthropicCUAClient.ts	5/5	Replaced console.error/console.warn with structured logger calls, added logger parameter to methods
packages/core/lib/v3/agent/GoogleCUAClient.ts	5/5	Updated error logging and added logger parameter to convertFunctionCallToAction and captureScreenshot
packages/core/lib/v3/agent/OpenAICUAClient.ts	5/5	Replaced console.error with structured logging, added logger parameter threading through methods
packages/core/lib/inferenceLogUtils.ts	5/5	Added console.warn to previously silent catch block for parse failures
packages/core/lib/v3/understudy/selectorResolver.ts	5/5	Added detailed error logging for CSS selector, XPath, and node resolution failures
packages/core/lib/v3/llm/aisdk.ts	5/5	Added logger parameter to createChatCompletion with fallback to instance logger

Sequence Diagram

sequenceDiagram
    participant Handler as v3CuaAgentHandler
    participant Client as AgentClient (Anthropic/Google/OpenAI)
    participant Action as Action Methods
    participant Screenshot as captureScreenshot
    participant Logger as Structured Logger
    
    Handler->>Client: execute(options)
    Note over Handler,Client: Pass logger to client
    
    Client->>Action: getAction(inputItems, logger)
    Note over Action: Was: console.error()<br/>Now: logger({category, message, level})
    
    Action-->>Logger: Log errors with stack trace
    Action-->>Logger: Log warnings with context
    
    Client->>Action: convertToolUseToAction(item, logger)
    Note over Action: Convert tool calls to actions
    Action-->>Logger: Log unknown tools, missing actions
    
    Client->>Screenshot: captureScreenshot(logger, options)
    Note over Screenshot: First param is now logger
    Screenshot-->>Logger: Log screenshot errors
    
    Handler->>Client: captureScreenshot(this.logger, {...})
    Note over Handler,Client: Handler passes its logger instance

[pirate]

@filip-michalsky check out the changes from https://github.com/browserbase/stagehand/pull/1283

hopefully it covers all your logging needs.

export BROWSERBASE_CONFIG_DIR=~/.config/browserbase    # set this in env / ~/.zshrc / ~/.bashrc

# example usage:
tsx run_any_script_that_imports_stagehand.ts

tail -f ~/.config/browserbase/sessions/latest/*.log           # follow all events in realtime
tail -f ~/.config/browserbase/sessions/latest/llm_events.log  # follow only LLM events
cat ~/.config/browserbase/sessions/latest/*.log | sort  # full output in chronological order

If you prefer not to persist logs you can also set BROWSERBASE_CONFIG_DIR=/tmp/browserbase or BROWSERBASE_CONFIG_DIR=. to put it in cwd.