Skip to content

Migrate all Stagehand templates to V4 - #101

Open
shrey150 wants to merge 18 commits into
devfrom
agent/update-templates-stagehand-v4
Open

Migrate all Stagehand templates to V4#101
shrey150 wants to merge 18 commits into
devfrom
agent/update-templates-stagehand-v4

Conversation

@shrey150

@shrey150 shrey150 commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Summary

Stagehand is the SDK for browser agents.

  • migrate every Stagehand template in this repository to the V4 lifecycle: 35 TypeScript, 32 Python, and 1 Go
  • use published @browserbasehq/stagehand@4.0.0 and stagehand==4.0.0 for the core SDKs
  • replace removed agent APIs with bring-your-own agent frameworks plus Stagehand code mode
  • adopt browserbase.launch() / localBrowser.launch(), Stagehand.create({ browser }), browser.context, V4 { data, metadata } envelopes, locator(), and explicit Stagehand-then-browser cleanup
  • validate live business outcomes instead of treating a completed API or browser call as success
  • update the docs and template index for V4

Companion PR: browserbase/create-browser-app#40

Agent migration: 14 templates

Nine TypeScript templates use Vercel AI SDK ToolLoopAgent with Stagehand code mode's stateful code_execute tool:

  • typescript/agent-with-human-in-loop
  • typescript/browser-agent-demo
  • typescript/business-lookup
  • typescript/company-address-finder
  • typescript/dynamic-form-filling
  • typescript/exa-browserbase
  • typescript/gemini-3-flash
  • typescript/gemini-cua
  • typescript/microsoft-cua

Five Python templates use Deep Agents with the Stagehand integration's stateful browser tools:

  • python/business-lookup
  • python/cerebras-docs-checker
  • python/company-address-finder
  • python/exa-browserbase
  • python/gemini-cua

The Go template's removed autonomous Sessions.Execute step is now an explicit, verifiable V4 ObserveAct → typed Extract workflow.

Package state

  • TypeScript core: published @browserbasehq/stagehand@4.0.0
  • Python core: published stagehand==4.0.0
  • TypeScript code mode: exact reviewed source commit 54302fc5f13be5ad8e717d8e1388502de22be2ed until @browserbasehq/stagehand-codemode is published
  • Python Deep Agents integration: current stagehand/main source (packages/integrations/deepagents), with its server dependency on published stagehand==4.0.0
  • Go V4 SDK: exact pseudo-version v0.0.0-20260810174315-a46676658b4f until the module is tagged

The code-mode Git dependency needs two temporary measures until publication: the pnpm subdirectory selector must be path:packages/integrations (no leading slash), and pnpm overrides must resolve the upstream monorepo's workspace: / catalog: dependencies. These are now present in all nine manifests.

Fresh E2E re-verification — 2026-08-18

This section replaces all historical E2E claims. Every executable entrypoint was freshly installed and invoked against the current PR head. No earlier run was counted as evidence.

There are 77 first-level language directories but 79 executable entrypoints: 68 Stagehand flows and 11 non-Stagehand flows. The previous description's “10 executable non-Stagehand flows” missed that both TypeScript and Python Playwright directories each contain two entrypoints.

Strict current result

  • 79/79 V4 entrypoints fresh-install successfully after commit f5a9cbd
  • 67/79 PASS
  • 7/79 BLOCKED on unavailable external credentials/quota
  • 2/79 FAIL
  • 2/79 FLAKY
  • 1/79 DEGRADED (reduced workload passes; default workload does not)
  • Stagehand subset: 56 PASS, 7 BLOCKED, 2 FAIL, 2 FLAKY, 1 DEGRADED
  • non-Stagehand subset: 11/11 PASS

The V3 side is a reconstructed behavioral baseline using the final V3 releases (@browserbasehq/stagehand@3.7.1, stagehand==3.22.0). A literal clean install of several base-branch manifests is no longer reproducible because they used latest or open-ended constraints that now resolve V4.

Legend: FIXED means the fresh pre-fix V4 run failed and the exact post-fix rerun passed. BLOCKED is not counted as a pass.

TypeScript Stagehand — 35 entrypoints

Template Fresh V3 Fresh V4 Evidence / finding
agent-with-human-in-loop BLOCKED PASS Production build plus real POST/SSE controller: resume accepted, human question answered, successful completion. V3 requires an unavailable direct Anthropic key.
amazon-global-price-comparison PASS PASS Valid regional products, currencies, and URLs.
amazon-product-scraping PASS PASS Three live products with validated URLs.
basic-caching FAIL FIXED Removed obsolete explicit Gemini model; repeated observation is a cache HIT.
basic-recaptcha PASS PASS Live CAPTCHA submission verified.
browser-agent-demo PASS PASS Source-installed code-mode agent returned grounded results.
browserbase-reducto FAIL PASS Downloaded and parsed the live Apple statement.
business-lookup PASS PASS Official SF registry result verified.
company-address-finder PASS PASS Four evidence-backed company results.
company-value-prop-generator FAIL PASS Live value proposition extracted and summarized.
context BLOCKED BLOCKED Missing SF_REC_PARK_EMAIL / SF_REC_PARK_PASSWORD.
council-events FAIL FIXED Uses current year, asserts non-empty events, and cleans up sequentially.
download-financial-statements FAIL PASS Four unique live PDFs archived.
dynamic-form-filling PASS PASS Synthetic form submitted and confirmation verified.
exa-browserbase PASS FAIL Default run failed 4/5 reviews; a one-company sequential rerun also failed. Result details are now printed before exit for diagnosis.
extend-browserbase FAIL PASS Live receipts downloaded and parsed.
form-filling PASS PASS All fields filled and read back.
gemini-3-flash PASS FLAKY Two fresh runs passed and one returned an empty/invalid final answer.
gemini-cua PASS FIXED Failed before prompt alignment; post-fix source-installed run returned two dated, cited results.
gift-finder PASS PASS Live products validated and ranked.
google-trends FAIL PASS Current US trends returned.
image-url-download FAIL FIXED Downloaded three non-empty images; cleanup errors no longer turn successful work into failure.
job-application FAIL PASS Synthetic submissions and confirmations verified.
license-verification FAIL FIXED V4-strict nullable schema plus identity/status assertions pass for DRE 02237476.
manual-mfa-with-contexts BLOCKED BLOCKED Missing user-scoped GitHub test login.
mfa-handling PASS PASS Live TOTP success verified.
microsoft-cua BLOCKED PASS V4 works through AI Gateway; V3 needs unavailable Azure credentials.
nurse-verification FAIL PASS Returned Ronald Agee, license 346, Active.
pickleball BLOCKED BLOCKED Missing SF Rec credentials; booking also requires explicit side-effect approval.
polymarket-research FAIL PASS Live market and current price data verified.
proxies PASS PASS Residential location and IP evidence verified.
proxies-weather PASS PASS Four proxy regions returned matching live weather/countries.
sec-filing-research FAIL PASS Five current EDGAR filings verified.
smart-fetch-scraper PASS PASS Required URL argument supplied; HTTP 200 content and links verified.
website-link-tester FAIL PASS Full 66-link audit completed in 171s with opt-in concurrency: 65 good links and one correctly detected live HTTP 500 (/templates/amazon-price-comparison). Expected nonzero exit proves the checker caught the site issue.

Python Stagehand — 32 entrypoints

Template Fresh V3 Fresh V4 Evidence / finding
amazon-global-price-comparison PASS PASS Live US/UK products, currencies, and URLs.
amazon-product-scraping PASS PASS Three live products validated.
basic-caching FAIL PASS Repeated cache HIT verified.
basic-recaptcha FAIL PASS Live CAPTCHA submission verified.
browserbase-reducto FAIL PASS Live PDF values verified.
business-lookup FAIL PASS Official registry result verified.
cartesia-form-filling FAIL PASS Direct browser E2E filled all nine fields, submitted the real test form, and verified visible confirmation; the voice server itself is intentionally long-running.
cerebras-docs-checker FAIL BLOCKED Live crawl/repository work completed, then every available model returned account HTTP 402.
company-address-finder FAIL PASS Four evidence-backed results.
company-value-prop-generator FAIL PASS Live extraction and one-liner verified.
context BLOCKED BLOCKED Missing SF Rec credentials.
council-events PASS PASS Current events with dates/times.
download-financial-statements FAIL PASS Four live PDFs archived.
exa-browserbase PASS DEGRADED One-company run passed in 169s; default five-company run timed out at 900s with CDP frame churn.
extend-browserbase PASS PASS Receipts downloaded and parsed.
form-filling PASS PASS Fields filled and read back.
gemini-cua FAIL FAIL Deep Agent/code-mode run ended in TaskGroup errors and repeated missing CDP sessions.
gift-finder PASS PASS Live products validated and ranked.
google-trends PASS PASS Current trends returned.
image-url-download FAIL PASS Three non-empty images downloaded with the required URL argument.
job-application FAIL PASS Synthetic application and confirmation verified.
license-verification PASS PASS DRE identity and status asserted.
manual-mfa-with-contexts BLOCKED BLOCKED Missing user-scoped GitHub test login.
mfa-handling PASS PASS Live TOTP success verified.
nurse-verification PASS FIXED Waits for the SPA, fills deterministic selectors, waits for the actual row, and verifies Ronald Agee 346.
pickleball BLOCKED BLOCKED Missing SF Rec credentials; booking additionally needs explicit approval.
polymarket-research PASS PASS Live market/price verified.
proxies PASS PASS IP and geolocation evidence verified.
proxies-weather PASS PASS Four regions returned matching live weather.
sec-filing-research PASS PASS Five current filings verified.
smart-fetch-scraper PASS PASS Required URL argument supplied; HTTP 200 content verified.
website-link-tester FAIL FLAKY Documented three-link run passed; 20-link stress run verified 19 and failed one structured-output parse.

Go Stagehand — 1 entrypoint

Template Fresh V3 Fresh V4 Evidence
hackernews PASS PASS Observed, opened, and cross-checked live story/comment data.

Non-Stagehand — 9 directories / 11 entrypoints

Entrypoint Fresh V3 Fresh V4
TypeScript getting-started-with-browserbase PASS PASS
TypeScript playwright/basic-recaptcha PASS PASS
TypeScript playwright/quickstart-playwright PASS PASS
TypeScript playwright-mfa-handling PASS PASS
TypeScript puppeteer/quickstart-puppeteer PASS PASS
TypeScript selenium/quickstart-selenium PASS PASS
Python getting-started-with-browserbase PASS PASS
Python playwright/basic-recaptcha PASS PASS
Python playwright/quickstart-playwright PASS PASS
Python playwright-mfa-handling PASS PASS
Python selenium/quickstart-selenium FAIL PASS

Fixes added from the fresh audit

Commit f5a9cbd:

  • makes all nine Git-pinned code-mode templates installable from a clean directory
  • removes the obsolete explicit model from TypeScript caching
  • makes council events use the current year and validate non-empty output
  • makes the DRE schema V4-strict and validates the returned identity/status
  • prevents cleanup-only failures from invalidating successful image downloads
  • makes Python nurse lookup deterministic around its client-rendered form/results
  • aligns Gemini CUA with the evidence-producing Gemini research prompt
  • preserves Exa failure details in output
  • adds opt-in link-checker concurrency while keeping the default at one

Repository proof

Check Fresh result
Root checks README index, Prettier, ESLint, Ruff lint, Ruff format, and git diff --check pass
Template inventory 43 README rows cover all 77 first-level directories
Code-mode installs 9/9 clean installs pass from the exact Git commit; binary startup verified
HITL Production Next build and real API/SSE flow pass against the source-installed code-mode package
Cartesia Direct nine-field browser fill, submit, and confirmation pass
Full link audit 66/66 processed; 65 good and one real HTTP 500 correctly reported
Secrets in commit No credential values or generated .env files are included

Remaining work before claiming 100%

  • fix TypeScript exa-browserbase (default and one-company runs fail)
  • stabilize Python exa-browserbase at the default five-company workload
  • fix Python gemini-cua CDP/TaskGroup failure
  • stabilize TypeScript gemini-3-flash and the Python link tester under repeated/stress runs
  • provide user-scoped SF Rec and GitHub test credentials through managed secrets, then rerun the six blocked authenticated flows; do not paste credentials into PR comments
  • restore Cerebras quota (or provide a replacement scoped key) and rerun its final verification
  • fix the live Browserbase homepage link returning HTTP 500
  • publish @browserbasehq/stagehand-codemode@4.0.0, then remove the temporary Git pin/overrides

Note

Cursor Bugbot will update its generated summary for the latest commit.

@socket-security

socket-security Bot commented Aug 9, 2026

Copy link
Copy Markdown

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action Severity Alert  (click "▶" to expand/collapse)
Warn High
Obfuscated code: npm json-schema is 90.0% likely obfuscated

Confidence: 0.90

Location: Package overview

From: ?npm/@ai-sdk/mcp@2.0.32npm/ai@7.0.66npm/json-schema@0.4.0

ℹ Read more on: This package | This alert | What is obfuscated code?

Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev.

Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code.

Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/json-schema@0.4.0. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

@shrey150
shrey150 marked this pull request as ready for review August 10, 2026 19:20
@shrey150
shrey150 requested a review from a team as a code owner August 10, 2026 19:20
Comment thread typescript/amazon-product-scraping/index.ts
Comment thread typescript/amazon-product-scraping/index.ts
Comment thread typescript/browserbase-reducto/index.ts
Comment thread python/cartesia-form-filling/stagehand_form_filler.py
Comment thread typescript/exa-browserbase/index.ts Outdated
Comment thread typescript/exa-browserbase/index.ts
@shrey150 shrey150 changed the title Update TypeScript templates to Stagehand V4 Migrate all Stagehand templates to V4 Aug 11, 2026
Comment thread go/hackernews/main.go
Comment thread python/cartesia-form-filling/stagehand_form_filler.py
Comment thread python/cartesia-form-filling/stagehand_form_filler.py
Comment thread python/exa-browserbase/main.py Outdated
Comment thread typescript/pickleball/index.ts

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit f5a9cbd. Configure here.

if (!selection.data.success) {
throw new Error(selection.data.message || `Could not select ${CURRENT_YEAR}`);
}
await page.waitForLoadState("domcontentloaded");

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Year filter wait is ineffective

Medium Severity

After selecting the calendar year, waitForLoadState("domcontentloaded") does not wait for the Legistar table refresh. The page is already at that load state from goto, and year changes on this ASP.NET calendar often update via postback/AJAX without a new document load, so extraction can run against a stale year view.

Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit f5a9cbd. Configure here.

console.log(`Found ${results.results.length} events`);
if (results.results.length === 0) {
throw new Error(`No ${CURRENT_YEAR} council events were extracted`);
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Missing year outcome validation

Medium Severity

The new success check only requires a non-empty event list for CURRENT_YEAR. It never verifies that extracted date values actually contain that year, so a stale or mis-filtered calendar table can still pass.

Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit f5a9cbd. Configure here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants