feat(mastra): add Stagehand code-mode integration

[shrey150]

Summary

• add a Mastra agent that launches the local Stagehand code-mode MCP over stdio
• keep one MCP client alive for the complete agent run so browser state survives tool calls
• load the shared Stagehand V4 syntax guide into the agent instructions
• add a real stdio discovery smoke and an isolated Mastra CI job

Stack

This PR is stacked on the Vercel AI SDK binding, which is stacked on the framework-neutral tool. Its diff contains only the Mastra integration.

Lifecycle

One MCPClient owns the local stdio process for the complete agent invocation. Mastra discovers the MCP tool as stagehand_code_execute, and the example disconnects the client in finally so the underlying browser and process are released.

E2E Test Matrix

Command / flow	Observed output	Confidence / sufficiency
Build the local code-mode package, then run pnpm --filter stagehand-codemode-mastra-example run smoke	Mastra launched the built stdio server, the server reported that it was listening on stdio, and discovery reported Mastra stdio discovery PASS: stagehand_code_execute.	Proves the real Mastra MCP adapter can launch the reviewed local stdio server, discover the tool, and receive the shared syntax guide. It does not make a provider-dependent model request.
pnpm --filter stagehand-codemode-mastra-example run check	TypeScript exited successfully.	Proves the agent and lifecycle code compile against the reviewed Mastra versions and local package.
Targeted ESLint and Prettier checks over the Mastra example, workspace, and workflow	Both completed without warnings or formatting differences.	Covers the complete changed TypeScript, JSON, YAML, and Markdown surface.

[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 execa is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: ? → npm/execa@9.6.1 ℹ 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/execa@9.6.1. 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]

Reviewed the Socket dependency report. execa@9.6.1 is a transitive dependency of the official @mastra/core / @mastra/mcp packages used by this binding, not a direct runtime dependency selected by the code-mode package. Both Socket checks pass, so I am retaining the framework dependency and leaving the alert visible rather than suppressing it.

[shrey150]

Superseded by browserbase/stagehand#2627, which keeps the Mastra example beside the canonical MCP build and tests both local and Browserbase startup.