feat(integrations): add Grok Build integration + Experimental ACP

[antonvishal]

What

Adds a Grok Build example that can use Stagehand through the existing facade.

Grok Build exposes ACP rather than a TypeScript SDK for driving the agent, so this adds a small ACP runner under integrations/core. The Grok-specific package only handles its CLI setup, authentication, and tool mapping.

The ACP process runs with the user's existing Grok login or XAI_API_KEY. The Stagehand MCP process receives only the environment variables it needs.

Question for maintainers

I put the ACP runner in integrations/core because it is not specific to Grok another ACP-compatible agent could use it by providing its own profile.

Does that feel like the right place for it?

If ACP is something we want to support as an integration path, I can also add a general ACP docs page. For this PR, I kept the documentation focused on Grok Build.

Testing

• pnpm check
• core integration tests
• Grok Build tests
• tested locally with an authenticated Grok Build install and a local browser

---

Summary by cubic

Adds a Grok Build integration over ACP and a reusable ACP runner, giving one persistent Stagehand browser with run, snapshot, and screenshot. Applies the same 60KB base64 screenshot cap to the ACP facade path to align with other transports.

• Adds a generic ACP client in @browserbasehq/stagehand-integrations/acp that initializes/authenticates, mounts the Stagehand facade as the only MCP server, approves only stagehand__run|snapshot|screenshot, cancels other tool requests and out-of-session prompts, and terminates the full agent process tree if unresponsive (including on Windows).
• Adds a facade launcher that starts the real stdio server with an allowlisted environment: only non-empty STAGEHAND_* and BROWSERBASE_* plus minimal OS runtime vars reach the facade; host secrets like XAI_API_KEY never do. Forwards signals reliably and passes --max-screenshot-base64-bytes=60000 to the facade.
• Implements a Grok-specific example in packages/integrations/grok-build that resolves @xai-official/grok, creates a disposable home/workspace and isolated GROK_HOME, prefers XAI_API_KEY auth then cached auth.json if available, deny-lists shell/file/subagent/plan/memory/web-search, and allowlists search_tool/use_tool to discover/invoke the Stagehand tools.
• Hardens shutdown: the facade server now handles repeated signals; the ACP bridge sends cancel, then SIGTERM/SIGKILL with a grace period, and cleans up descendants.
• Docs: adds a Grok Build page and icon, updates the integrations overview to include Grok Build and explain the ACP path, and lists Grok in the package overview. Notes BROWSERBASE_PROJECT_ID is optional.
• No migrations. New deps: @agentclientprotocol/sdk and @xai-official/grok. To try locally: build @browserbasehq/stagehand-integrations, set XAI_API_KEY (or run grok login), then run the packages/integrations/grok-build example.

^{Written for commit 6219756. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 6219756

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

This PR is from an external contributor and must be approved by a stagehand team member with write access before CI can run.
Approving the latest commit mirrors it into an internal PR owned by the approver.
If new commits are pushed later, the internal PR stays open but is marked stale until someone approves the latest external commit and refreshes it.

[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/​@​xai-official/​grok@​1.0.5
	npm/​@​agentclientprotocol/​sdk@​1.3.0

View full report

[cubic-dev-ai]

All reported issues were addressed across 25 files

Architecture diagram

sequenceDiagram
    participant CLI as Grok CLI (user CLI)
    participant ACP as ACP Client (Stagehand)
    participant AGENT as Grok Agent Process
    participant FACE as Facade MCP Server (Stagehand)
    participant STAGE as Stagehand Core
    participant BROWSER as Browser

    Note over CLI,ACP: User runs: pnpm --dir packages/integrations/grok-build start -- "task"
    CLI->>ACP: runGrokBuild(instruction)
    ACP->>ACP: Create disposable runtime (home, cwd, GROK_HOME, agent profile)
    ACP->>AGENT: Spawn grok CLI with ACP stdio + restricted tools
    ACP->>AGENT: ACP initialize
    AGENT-->>ACP: Initialize response with auth methods
    alt XAI_API_KEY exists
        ACP->>AGENT: Authenticate via xai.api_key
    else cached auth.json only
        ACP->>AGENT: Authenticate via cached_token
    end
    ACP->>AGENT: session.new with Stagehand facade as only MCP server
    AGENT->>FACE: Launch facade stdio server (via launcher binary)
    FACE->>STAGE: Initialize Stagehand (lazily start browser)
    STAGE->>BROWSER: Start persistent browser session
    ACP->>AGENT: Prompt with task + Stagehand instructions
    AGENT->>AGENT: Discover MCP tools (run, snapshot, screenshot)
    AGENT->>ACP: Permission request for Stagehand tool
    alt Tool is stagehand__run/snapshot/screenshot
        ACP->>AGENT: Allow once
    else Other tool (shell, file, etc.)
        ACP->>AGENT: Reject or cancel
    end
    AGENT->>FACE: MCP tool call (e.g., stagehand__run)
    FACE->>STAGE: Execute browser automation
    STAGE->>BROWSER: Navigate, act, snapshot, screenshot
    BROWSER-->>STAGE: Results
    STAGE-->>FACE: Tool result
    FACE-->>AGENT: Tool response
    AGENT-->>ACP: Stream text messages (agent updates)
    ACP-->>CLI: Final assistant response

    Note over ACP,AGENT: On abort/signal
    ACP->>AGENT: ACP session.cancel
    ACP->>AGENT: SIGTERM to process tree
    opt No graceful exit
        ACP->>AGENT: SIGKILL to process tree
    end
    ACP->>ACP: Clean up disposable runtime directories

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 8 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>