[pull] main from browserbase:main - #181
Merged
Merged
Conversation
pi ships without built-in MCP by design, so this is a native pi extension (pi-package manifest, installable via `pi install`, loadable one-off with `pi -e`): the three facade tools registered with descriptions, runtime validators, and `FACADE_AGENT_INSTRUCTIONS` imported from `@browserbasehq/stagehand-integrations/facade`; TypeBox param schemas; lazy browser launch on first tool call, closed on `session_shutdown`; screenshots as native image content. Contract drift test + turbo typecheck entry. One-line run after `pnpm install` + core build: `pnpm --filter @browserbasehq/stagehand-integrations-example-pi-facade start "your instruction"` Verified: Browserbase smoke via pi 0.84.2 — "The page heading is 'Example Domain' [0-19]". <!-- This is an auto-generated description by cubic. --> --- ## Summary by cubic Exposes Stagehand’s facade tools (`run`, `snapshot`, `screenshot`) as native `pi` tools so `pi` can use the canonical facade without MCP. Also fixes shutdown to close the browser even if a launch is still pending. - Registers the three tools with canonical descriptions; validates params via TypeBox and re-validates with contract schemas at execution; forwards `FACADE_AGENT_INSTRUCTIONS` on `run` (from `@browserbasehq/stagehand-integrations/facade`). - Launches the browser lazily on first tool call (Browserbase or local per env); on `session_shutdown` waits for any in-flight launch and then closes Stagehand and the browser. Returns screenshots as native image content. - Security: model-authored JS runs in the Stagehand extension service worker; Browserbase is the recommended isolation boundary; only `STAGEHAND_*`/`BROWSERBASE_*` envs configure the browser; `pi` model credentials never reach the browser session. - Tests assert only the canonical tools register, descriptions match, guidelines pass through, and no browser launches at registration. - Package `@browserbasehq/stagehand-integrations-example-pi-facade` includes a `pi` manifest and is installable via `pi`, or loadable with `pi -e`. Requires Node 24+, `pi` >= 0.84.2, Browserbase credentials, and a supported model API key. <sup>Written for commit 8b01a10. Summary will update on new commits.</sup> <a href="https://cubic.dev/pr/browserbase/stagehand/pull/2718?utm_source=github" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img alt="Review in cubic" src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a> <!-- End of auto-generated description by cubic. -->
![https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source](https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source){kind=link}
![https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img](https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img){kind=link}
![https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a](https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a){kind=link}
Runnable project embedding a Claude agent via
`@anthropic-ai/claude-agent-sdk`, with the `stagehand-facade` stdio
server mounted programmatically — matching the pattern established by
the evals `claude_code` harness (`query()` + `mcpServers`).
- `allowedTools` restricted to
`mcp__stagehand__{run,snapshot,screenshot}` plus a `canUseTool` guard
(headless runs hang on unanswered permission prompts).
- System prompt is `FACADE_AGENT_INSTRUCTIONS` imported from the facade
package; server spawned with a `STAGEHAND_*`/`BROWSERBASE_*` env
allowlist.
- One-line run after install + core build: `pnpm --filter
@browserbasehq/stagehand-integrations-example-claude-code-facade start
"your instruction"`
- Secondary README section: connecting a running Claude Code CLI via the
project-scoped `.mcp.json` (verified: the CLI inherits the shell env;
`${VAR}` in .mcp.json is not expanded).
Verified: contract + allowlist tests in CI; Browserbase smoke — *"The
page heading is 'Example Domain', per snapshot element [0-19]"*.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds a runnable Claude agent harness using
`@anthropic-ai/claude-agent-sdk` that mounts the Stagehand facade MCP
stdio server. Provides a one-command example and an optional `.mcp.json`
for the Claude Code CLI; only `STAGEHAND_*`/`BROWSERBASE_*` env reach
the browser.
- New package:
`@browserbasehq/stagehand-integrations-example-claude-code-facade` (Node
24+). Run: `pnpm --filter
@browserbasehq/stagehand-integrations-example-claude-code-facade start
"your instruction"`. Choose model via `CLAUDE_STAGEHAND_MODEL` (default
`claude-sonnet-5`).
- Spawns `@browserbasehq/stagehand-integrations/facade/stdio-server`
with an env allowlist; `ANTHROPIC_API_KEY` is never forwarded.
- Restricts tools to `mcp__stagehand__{run,snapshot,screenshot}` via
`allowedTools` and a deny-by-default `canUseTool`. Uses
`FACADE_AGENT_INSTRUCTIONS` as the system prompt.
- `.mcp.json` enables the `claude` CLI in this directory; the CLI
inherits the shell env (note: `${VAR}` is not expanded in `.mcp.json`).
- Tests cover the tool name contract and env allowlist. Robustness:
resolve server path inside `main`, add `import.meta.main` guard, and
exit nonzero if the agent stream ends without a result. Workspace
updates add `@anthropic-ai/claude-agent-sdk` to the catalog/lockfile and
a `turbo` typecheck target; no changes to other packages’ runtime
behavior.
<sup>Written for commit 129610f.
Summary will update on new commits.</sup>
<a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2719?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->
Runnable project embedding a Codex agent via `@openai/codex-sdk` (pinned
to the evals-proven 0.125.0), with the `stagehand-facade` stdio server
mounted through the SDK's config override — `config: { mcp_servers: ...
}`, the same mechanism the evals codex harness uses (codex-sdk has no
in-process MCP mounting).
- `approvalPolicy: "on-failure"` chosen empirically: `never` and
`untrusted` auto-cancel MCP tool calls ("user cancelled MCP tool call");
`on-failure` completes them. Local sandbox stays `read-only` — browser
work happens in the MCP server.
- Env allowlist (`STAGEHAND_*`/`BROWSERBASE_*`) to the spawned server;
Codex model default left harness-tuned (`CODEX_STAGEHAND_MODEL` to
override).
- `CODEX_PATH_OVERRIDE` escape hatch (evals' `EVAL_CODEX_PATH` pattern)
for package managers that skip the SDK's vendored-binary postinstall —
pnpm does.
- One-line run after install + core build: `pnpm --filter
@browserbasehq/stagehand-integrations-example-codex-facade start "your
instruction"`
- Secondary README section: connecting a running `codex` CLI
(config.toml template or per-invocation `-c` overrides).
Verified: config + allowlist tests in CI; Browserbase smoke — *"The page
heading is 'Example Domain' [0-19]"* (run → snapshot sequence confirmed
via event stream).
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds a runnable `@openai/codex-sdk` example that mounts the Stagehand
facade MCP server via the SDK config override, enabling Codex-driven
browser work without touching existing packages. Sets
`approvals_reviewer: "auto_review"`, longer MCP timeouts, and pins
`@openai/codex-sdk` to 0.147.0 so headless tool calls succeed on clean
installs.
- Builds MCP config in code (`mcp_servers.stagehand` → `node
<facade/stdio-server>`), allowlists only `STAGEHAND_*`/`BROWSERBASE_*`
env vars, and uses `approvalPolicy: "on-failure"` with `sandboxMode:
"read-only"`.
- Supports `OPENAI_API_KEY`, optional `CODEX_STAGEHAND_MODEL`, and
`CODEX_PATH_OVERRIDE` for environments missing the SDK’s vendored
binary. Includes a `config.toml` and CLI README for wiring a running
`codex` CLI via `-c` overrides. Adds
`@browserbasehq/stagehand-integrations-example-codex-facade` and a
`turbo` typecheck target; tests cover MCP mounting and env allowlisting.
**Run/rollout**
- Requires Node 24+. Build `@browserbasehq/stagehand-integrations`
first, then run: pnpm --filter
`@browserbasehq/stagehand-integrations-example-codex-facade` start
"instruction".
- Set `OPENAI_API_KEY` (or use `codex login`) and Browserbase vars:
`BROWSERBASE_API_KEY`, optional `BROWSERBASE_PROJECT_ID`. Optional:
`CODEX_STAGEHAND_MODEL`, `CODEX_PATH_OVERRIDE`.
- No migrations; the workspace pins `@openai/codex-sdk@0.147.0`.
<sup>Written for commit 29acbd2.
Summary will update on new commits.</sup>
<a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2720?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
See Commits and Changes for more details.
Created by
pull[bot] (v2.0.0-alpha.4)
Can you help keep this open source service alive? 💖 Please sponsor : )