Skip to content

[api] store frame ID map #907

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 12 commits into from
Jul 25, 2025
Merged

[api] store frame ID map #907

merged 12 commits into from
Jul 25, 2025

Conversation

seanmcguire12
Copy link
Member

why

  • to enable multi-tab handling on the Stagehand API

what changed

  • added a mapping of CDP Frame ID -> Page objects
    • frame IDs are now included in the payload for API request so that the API knows which page to take the action on

test plan

  • act evals
  • regression evals
  • extract evals
  • observe evals

Copy link

changeset-bot bot commented Jul 23, 2025

🦋 Changeset detected

Latest commit: 78940d4

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

Copy link
Contributor

@greptile-apps greptile-apps bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Greptile Summary

This PR implements frame ID mapping functionality to enable multi-tab handling for the Stagehand API. The changes introduce a systematic way to track and identify specific browser tabs/frames when executing operations through the API.

The implementation adds a frameId property to core operation interfaces (ActOptions, ExtractOptions, ObserveOptions, and GotoOptions), allowing frame identification to be passed throughout the system. A new frame ID mapping system is implemented in StagehandContext with methods to register, unregister, and lookup pages by frame ID using a Map data structure for O(1) performance.

StagehandPage now tracks its CDP (Chrome DevTools Protocol) frame ID through automatic retrieval during initialization and exposes it via a public frameId getter. The page handles frame navigation events to update the mapping when root frames change, and automatically unregisters frame IDs when pages close to prevent memory leaks.

All API method calls (act, extract, observe, goto) now include the frame ID in their parameters, enabling the remote API to route operations to the correct page. A critical bug fix in lib/api.ts ensures that when calling extract without a schema, all options (including frameId) are properly passed instead of being ignored.

This architecture enables the Stagehand API to maintain session state across multiple tabs and correctly execute operations in complex multi-tab scenarios where pages might be created, destroyed, or navigated independently.

Confidence score: 4/5

• This PR is generally safe to merge with solid implementation but has some minor lifecycle management concerns
• The implementation is well-structured and follows good practices, but lacks automatic cleanup validation and duplicate registration handling
• The lib/api.ts extract method fix needs attention as it was previously ignoring critical options

5 files reviewed, no comments

Edit Code Review Bot Settings | Greptile

@seanmcguire12 seanmcguire12 added act These changes pertain to the act function extract These changes pertain to the extract function observe These changes pertain to the observe function labels Jul 23, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
act These changes pertain to the act function extract These changes pertain to the extract function observe These changes pertain to the observe function
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants