Update TypeScript templates to Stagehand V4

[shrey150]

Summary

• migrate all 35 Stagehand TypeScript templates to the V4 lifecycle and pin the 12 direct SDK manifests to the published @browserbasehq/stagehand@4.0.0
• replace all nine historical TypeScript stagehand.agent() examples with bring-your-own Vercel AI SDK ToolLoopAgent workflows using Stagehand code mode's single stateful code_execute MCP tool
• pin those nine agent templates to the unpublished @browserbasehq/stagehand-codemode source at browserbase/stagehand@54302fc5f13be5ad8e717d8e1388502de22be2ed and add standalone manifests where the templates previously relied on ambient dependencies
• preserve human-in-the-loop behavior through an application-defined askHuman tool, SSE updates, and Browserbase live view discovery
• harden six templates against issues found during live outcome testing: a retired Stripe URL, nullable SF business data, Philadelphia's year selector wording, TOTP expiry/retry behavior, and stale/ambiguous Polymarket search guidance
• update documentation and positioning with the lead: Stagehand is the SDK for browser agents.

Vercel AI SDK is used here because the packaged code-mode tool is a local stdio MCP server and AI SDK supports stdio directly. Eve's current TypeScript MCP connection is oriented around deployed Streamable HTTP/SSE endpoints, so Eve is the better follow-up option once code mode has a remote gateway rather than for these standalone local templates.

Temporary packaging note

The core SDK is now published. This PR uses exact @browserbasehq/stagehand@4.0.0 registry dependencies in all 12 direct SDK manifests, and clean consumer installs plus a real local-browser runtime have passed.

@browserbasehq/stagehand-codemode is not published yet: the public npm registry returns 404 and its publication PR remains open as a draft. The nine agent templates therefore retain the reviewed GitHub source pin at 54302fc5f13be5ad8e717d8e1388502de22be2ed. That raw subdirectory source is not directly consumer-installable because it contains workspace/catalog: dependencies and no built dist; code-mode verification below uses a locally built and packed artifact from that exact commit together with the published SDK. Keep this PR as a draft until code mode is published, then replace those final nine pins/TODOs with @browserbasehq/stagehand-codemode@4.0.0 and rerun the matrix.

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

Stagehand code-mode package PR: browserbase/stagehand#2644

E2E Test Matrix

No Browserbase, AI Gateway, model-provider, Exa, Extend, or Reducto credentials were available in this workspace. I therefore ran every migrated template at the highest honest level available: exact entrypoint/package runtime where possible, otherwise its real public target and expected business outcome. Target-level below is deliberately not represented as an exact credentialed template run.

Cross-template and package proof

Command / flow	Observed output	Confidence / sufficiency
Public registry metadata for @browserbasehq/stagehand@4.0.0	npm latest resolves to 4.0.0; tarball has a registry integrity hash, Node >=22.18.0, and fully resolved dependencies (no workspace:/catalog: specs)	High: proves the intended core package is actually published
Empty consumer install + published local-browser runtime	Fresh npm project installed 49 packages; imports exposed Stagehand, browserbase, and localBrowser; Stagehand initialized a real local Chrome session, loaded Example Domain with HTTP 200, and read title/heading Example Domain	High: exercises the registry artifact and extension at runtime without repository links
Exact code-mode 54302fc typecheck + tests + pack	Generated content current; 9 test files and 68 tests passed; publint passed; tarball contained executable, skill, and reference assets	High: validates the exact temporary code-mode source
Packaged code-mode lifecycle smoke	code_execute, EOF cleanup, SIGINT/SIGTERM cleanup, and hard-timeout checks passed	High: exercises the installed CLI artifact and lifecycle
Vercel AI SDK ToolLoopAgent → exact packed code mode → published SDK → real local Chrome	Three model turns; stateful code_execute calls returned the live SF business record and intended Polymarket market; agent returned Verified live business and market outcomes.	High: proves the published core SDK works with the selected BYOA/code-mode architecture; model decisions were deterministic because no provider key was available
Clean registry installs for direct SDK manifests	12/12 installed independently from npm and each resolved exactly Stagehand 4.0.0 with the expected three public exports	High: covers every manifest changed from the temporary SDK pin
Remaining code-mode manifests	Prior exact-pack run installed 9/9; latest combined harness and HITL app resolved exact packed code mode 4.0.0 → published Stagehand 4.0.0	Medium-high until the code-mode registry artifact exists; raw GitHub source remains intentionally non-installable
Script template strict TypeScript checks	34/34 Stagehand/code-mode entrypoints passed together against the published SDK plus exact packed code mode	High: covers every script-style migrated template against the final core artifact
Human-in-the-loop Next app	Fresh install resolved code mode 4.0.0 → published Stagehand 4.0.0; tsc --noEmit and production next build passed with all app/API routes generated	High: covers the non-script template against the published core artifact
TypeScript → JavaScript/playground generation	Local API fixture built 34 TypeScript files + 68 assets and validated 34/34 runnable sources	High: validates all runnable generated entrypoints
Production playground endpoint	https://www.browserbase.com/website-api/templates now returns a 307 Clerk sign-in redirect to unauthenticated CI clients; the validator consequently receives HTML	External blocker: reproduced independently of this branch; local full fixture passes
Repository checks	README index (43 rows / 77 dirs), Prettier, ESLint, and git diff --check passed	High for the changed TypeScript/docs
Full pnpm check Python tail	Ruff reports 11 lint errors and 3 unformatted files, all byte-identical to origin/dev; this PR does not change Python	Pre-existing baseline failure, not hidden or modified here

Per-template live outcome audit

Template	Highest test performed	Observed output / outcome
agent-with-human-in-loop	Build + live target	Next typecheck/build passed. Live careers site showed four open positions; the Software Engineer form exposed required name/email/phone/resume fields and optional LinkedIn/cover letter. No real application was submitted.
amazon-global-price-comparison	Build + live target	Dedicated package build passed. Amazon returned its “continue shopping” automation gate locally, so country-proxy price comparison needs Browserbase credentials/verified sessions.
amazon-product-scraping	Live target	Amazon was reachable but gated local automation; exact extraction needs Browserbase/model credentials.
basic-caching	Live business outcome	The old /preview target redirected/404ed. Updated target loaded embedded Stripe Checkout; email, 4242 4242 4242 4242, expiry 12 / 34, and all iframe-backed values were filled and retained.
basic-recaptcha	Live target	Google reCAPTCHA demo returned 200 and rendered challenge/widget frames. Solving is intentionally unverified without a Browserbase captcha-enabled session.
browser-agent-demo	Packaged agent-loop proof + target checks	Exact AI SDK/MCP/local-browser architecture completed live code_execute work. Template-specific Browserbase Search and Fetch calls remain credential-blocked.
browserbase-reducto	Live target	Apple target is Cloudflare-blocked (403) from the local runner; exact PDF download/Reducto extraction also requires Browserbase and Reducto credentials.
business-lookup	Packaged agent-loop live outcome	Returned Jalebi Street, certificate 1164514, location 1376013-12-241, Haight Ashbury, and a missing NAICS value. This exposed and fixed the schema's incorrect non-null NAICS assumption.
company-address-finder	Live business outcome	Official pages yielded Browserbase 1 Post Street, Floor 15, Mintlify 1 Post St, 1800, and Reducto 717 California Street; Wordware's official terms/privacy pages were reachable but no address was found, matching nullable output semantics.
company-value-prop-generator	Live business outcome	Browserbase homepage returned 200 with current positioning: “Give your agents access to the whole web” and “makes the web as reliable and programmable as APIs.”
context	Live target	SF Rec & Park loaded and exposed login/sign-up/court-reservation surfaces. Context persistence and deletion require Browserbase plus an authenticated REC.US account.
council-events	Live business outcome	Philadelphia Legistar's 2025 year view returned City Council (12/11/2025 10:00 AM), Public Property/Public Works (9:15 AM), and Appropriations (9:00 AM). Live inspection found the control is a year selector, and code/docs were corrected.
download-financial-statements	Live target	Apple Investor is 403 from the local runner, so Browserbase PDF download/screenshot behavior remains credential-blocked.
dynamic-form-filling	Live side effect	The public trip-planning Google Form was filled and actually submitted; confirmation read Your response has been recorded.
exa-browserbase	Static/package + downstream target	Exact agent/code-mode integration installs and typechecks. Exa discovery and multi-company application flows require an Exa key, model key, and Browserbase sessions; no external applications were submitted.
extend-browserbase	Live business outcome	Expense portal exposed 19 receipts; the first receipt downloaded as a valid image/jpeg, HTTP 200, 433,878 bytes. Extend parsing remains key-blocked.
form-filling	Live business outcome	Browserbase contact form accepted and retained all six intended fields (name, email, title, company, project). Submission was intentionally not triggered.
gemini-3-flash	Target-level research	The requested eclipse facts were cross-checked against NASA: Aug. 12, 2026 total eclipse with partial visibility in North America, followed by Aug. 2, 2027 partial visibility in eastern Canada/northern Maine. Exact Gemini agent run needs credentials.
gemini-cua	Target-level research	Same live NASA outcome verified; exact Gemini CUA/browser session is credential-blocked.
gift-finder	Live business outcome	Firebox search returned product sets for the example terms: 12 for “spice rack”, 0 for “chef knife”, 2 for “herb garden”, and 12 for “mug” (89 products advertised overall). This verifies aggregation while documenting weak/empty individual queries.
google-trends	Live business outcome	Current US trends page returned 26 rows, including don nelson, dalton and sako, mexico vs usa u20, and arsenal vs dortmund.
image-url-download	Live business outcome	Browserbase homepage exposed 24 images; the first five downloaded successfully as valid WebP/SVG assets (about 2.6 KB–246 KB).
job-application	Live side effect	On the template's synthetic agent job board, the Senior Web Automation Specialist application was actually submitted; confirmation said the deployment request was received. The jobs page currently lists 9 missions while its homepage says 18, a target-data inconsistency.
license-verification	Live business outcome	California DRE license 02237476 returned Rohin Razdan Dhar, SALESPERSON, LICENSED, expiry 06/03/28, broker Side, Inc. 02014153, and no disciplinary action.
manual-mfa-with-contexts	Live target	GitHub login is reachable. A real account, manual MFA approval, and Browserbase context credentials are required, so the exact persistence workflow was not impersonated.
mfa-handling	Live business outcome	The template's RFC 6238 algorithm and published demo credentials reached /loginSuccess/. Testing exposed near-expiry and failed-page retry races; both were fixed with a fresh-window wait, deterministic locators, and retry navigation/refill.
microsoft-cua	Target-level research	Same live NASA eclipse outcome verified; exact Microsoft CUA/browser session is credential-blocked.
nurse-verification	Live target + issue discovery	Target loads a Person Search for the Alabama Board of Podiatry, not nursing, and an unsolved Turnstile blocks local search. The template's name/domain mismatch is documented; exact results require anti-bot solving.
pickleball	Live target	REC.US SF recreation surface loaded with court-reservation UI. No account was available, so no real court booking or purchase was attempted.
polymarket-research	Packaged agent-loop live outcome	Live market resolved to Will Elon Musk rejoin the Trump Administration in 2026?; latest retest returned live Yes/No buttons (9.6¢ / 96.3¢ at that moment). Prices are dynamic and are not fixed in the template. Stale query and “first result” ambiguity were replaced with an explicit current title.
proxies	Live baseline	Local ipinfo resolved Boardman, Oregon / AS16509. Exact New York Browserbase geolocation proof requires Browserbase credentials.
proxies-weather	Build + live target	Dedicated package build passed and Windy returned 200. Exact weather/geolocation comparison remains Browserbase proxy-blocked.
sec-filing-research	Live business outcome	Official SEC submissions JSON returned Apple Inc.'s latest 10-Q filed 2026-07-31, accession 0000320193-26-000020. SEC's browser search UI rate-limited the local runner (403), so the cloud UI flow still needs Browserbase.
smart-fetch-scraper	Live business outcome	Hacker News returned 200, 34,916 bytes, title Hacker News, 228 links, and content density 0.1204. Browserbase Fetch transport itself remains credential-blocked.
website-link-tester	Live business outcome	Discovered 66 unique HTTP links on Browserbase; 65 returned below 500. The one real failure was /templates/amazon-price-comparison returning 500, a live website route issue surfaced by this audit.

Python templates are intentionally unchanged because this migration is scoped to the TypeScript Stagehand V4 API.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​types/​node@​22.20.1
	npm/​@​ai-sdk/​mcp@​2.0.29
	npm/​ai@​7.0.58

View full report

[socket-security]

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		Obfuscated code: npm json-schema is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: ? → npm/@ai-sdk/mcp@2.0.29 → npm/ai@7.0.58 → npm/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