cdp debug logging [STG-593]

[the-roaring]

why

make the relationship between stagehand and playwright's APIs easier to debug

what changed

added a debug logger type sh:protocol that can be invoked along with playwright debug logs with an envvar e.g. DEBUG=pw:api,pw:browser*,sh:protocol

[changeset-bot]

⚠️ No Changeset found

Latest commit: 0d95263

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.

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]

Greptile Summary

This PR introduces a comprehensive CDP (Chrome DevTools Protocol) debug logging system to help developers distinguish between CDP calls made by Stagehand versus Playwright directly. The implementation adds a new debug namespace sh:protocol that can be used alongside Playwright's existing debug logs.

The core functionality works by:

1. Automatic protocol enabling: When sh:protocol is specified in DEBUG, it automatically enables Playwright's pw:protocol logging
2. stderr interception: The system intercepts process.stderr.write to rewrite Playwright's protocol logs, changing pw:protocol to sh:protocol for calls that originated from Stagehand code
3. Call tracking: A markStagehandCDPCall() function tracks pending CDP calls with method names and session IDs to correlate with actual protocol messages
4. Integration points: The debug markers are strategically placed throughout the codebase in StagehandPage.ts, StagehandContext.ts, a11y/utils.ts, and the main index.ts

Additionally, the PR includes:

• A new createStagehandApiLogger() utility that formats Stagehand logs to match Playwright's debug output format with sh:api namespace
• Example files demonstrating the debug functionality
• Formatting improvements applied by Prettier across several test files
• Addition of *.log to .gitignore

This enhancement allows developers to use environment variables like DEBUG=pw:api,pw:browser*,pw:protocol*,sh:protocol to get unified debug output where they can clearly see which CDP operations are initiated by Stagehand's high-level abstractions versus Playwright's internal operations.

Confidence score: 3/5

• This PR introduces complex global state mutations and stderr interception that could cause unexpected behavior in production environments
• The implementation has several potential race conditions in call tracking logic and lacks robust error handling around the stderr interception
• Files needing more attention: lib/debug.ts (global process modifications), lib/StagehandPage.ts (integration points), lib/index.ts (CDP call integration)

_{9 files reviewed, 1 comment}

_{Edit Code Review Bot Settings | Greptile}

[greptile-apps]

Greptile Summary

This review covers only the changes made since the last review (commit e4f1e10), not the entire PR. The latest change simplifies the example script by removing the explicit API logging configuration. The developer removed the createStagehandApiLogger() import and its usage from the Stagehand initialization in examples/example.ts, leaving only the spread StagehandConfig. This change aligns with the PR's goal of consolidating debug logging into a unified system that uses environment variables (DEBUG=sh:protocol) to automatically intercept and mark Stagehand-originated CDP calls within Playwright's existing debug infrastructure.

This modification improves the developer experience by eliminating the need to manually configure API logging in examples while maintaining the sophisticated debugging capabilities through the new debug system that can distinguish between Playwright and Stagehand protocol calls.

Confidence score: 5/5

• This PR is safe to merge with minimal risk
• Score reflects simple cleanup changes that remove outdated manual logging configuration in favor of the new automated debug system
• No files require special attention

_{1 file reviewed, no comments}

_{Edit Code Review Bot Settings | Greptile}

[the-roaring]

to generate CDP message logs with this, set the DEBUG env var:

DEBUG=pw:api,pw:browser*,pw:protocol*,sh:protocol pnpm run example &> pw.log

to use the logger function that formats stagehand method logs into the same format (labeled sh:api) so they are visible in context with the CDP message logs:

import { createStagehandApiLogger } from "../lib/stagehandApiLogger";


// create stagehand object with the logger
const stagehand = new Stagehand({
    logger: createStagehandApiLogger(),
    ...StagehandConfig,
  });

you can generate a more readable version of the logs with this one liner:

grep -E "(pw|sh):protocol" pw.log | sed -E -e 's/.*(pw|sh):protocol (SEND ►) \{"id":([0-9]+),"method":"([^"]+)".*$/\1:protocol \2 [id:\3] \4/' -e 's/.*(pw|sh):protocol (◀ RECV) \{"id":([0-9]+),"result":.*$/\1:protocol \2 [id:\3] RESPONSE/' -e 's/.*(pw|sh):protocol (◀ RECV) \{"method":"([^"]+)".*$/\1:protocol \2 [event] \3/' | grep -E "(SEND ►|◀ RECV)" > pw_compressed.log