[api] update root frame ID on init

[seanmcguire12]

why

• tab handling for act, extract and observe was failing because we sometimes sent frameId: undefined after a new page had been opened
• the rootFrameId only became available after Page.frameNavigated fired, so the time between the event firing and a stagehand API call caused undefined frameIds

what changed

• Added getCurrentRootFrameId helper which calls Page.getFrameTree to fetch the current root frame ID on page creation
• attachFrameNavigatedListener is now called right after a page is wrapped with createStagehandPage
• handleNewPlaywrightPage now runs before attaching the listener

test plan

• tested in local dev
• run all evals

[changeset-bot]

🦋 Changeset detected

Latest commit: 52f0974

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

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

[greptile-apps]

Greptile Summary

This PR fixes a critical race condition in frame ID handling that was causing tab operations (act, extract, and observe) to fail. The core issue was that frameId: undefined was being sent to API calls when operations occurred on newly opened pages before the frame ID was properly initialized.

The problem stemmed from the timing of frame ID availability - the rootFrameId only became available after the Page.frameNavigated event fired, creating a window where API calls could be made with undefined frame IDs. This was particularly problematic for tab handling scenarios where pages are created dynamically.

The solution involves three key architectural changes:

1. Proactive Frame ID Fetching: A new getCurrentRootFrameId helper function was added that uses the Chrome DevTools Protocol (CDP) Page.getFrameTree command to immediately fetch the root frame ID during page initialization, eliminating the need to wait for the Page.frameNavigated event.

2. Restructured Initialization Flow: The page creation flow in StagehandContext.ts was reorganized so that attachFrameNavigatedListener is called immediately after page wrapping, and handleNewPlaywrightPage runs before listener attachment. This ensures frame IDs are available before any operations can occur.

3. Consistent Frame ID Usage: All API calls throughout StagehandPage.ts were updated to use this.rootFrameId instead of this.frameId, providing better semantic clarity and ensuring consistent frame identification across operations.

The changes integrate well with the existing CDP-based architecture and maintain compatibility with Stagehand's page proxy system while solving the timing issues that were causing tab handling failures.

Confidence score: 4/5

• This PR addresses a specific, well-identified race condition with a targeted technical solution
• The changes show careful consideration of initialization order and timing issues
• The files StagehandPage.ts and StagehandContext.ts need attention due to the complexity of the event handling and CDP integration changes

_{2 files reviewed, no comments}

_{Edit Code Review Bot Settings | Greptile}