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 an experimental Grok Build integration and reusable ACP runner so one persistent Stagehand browser serves run, snapshot, and screenshot. Grok Build is now also available as an executable eval harness with isolated credentials, tool mounts, trajectories, and usage metrics.

Integration

• Supports XAI_API_KEY or cached grok login authentication in disposable runtime directories.
• Restricts Grok to MCP discovery and invocation while disabling shell, files, subagents, plan mode, memory, and web search.
• Applies the existing 60 KB screenshot limit to ACP-launched facades and forwards only required environment variables.
• Adds setup documentation, navigation, and local usage instructions; BROWSERBASE_PROJECT_ID remains optional.

Eval harness

• Registers grok_build for Stagehand, Playwright MCP, and Chrome DevTools MCP surfaces.
• Captures native streaming tool calls, observations, trajectories, token usage, cost, cancellation, and cleanup.
• Adds @agentclientprotocol/sdk, @xai-official/grok, smol-toml, and the private @browserbasehq/stagehand-integrations-grok-build-sdk package; no migrations are required.

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: 46a63e6

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>

[antonvishal]

The fork branch was renamed to grok-build. GitHub closed this cross-fork PR instead of retargeting it, so the updated work continues in #2876.