feat(integrations): add Cursor SDK integration

[antonvishal]

why

Add a Cursor SDK example alongside the existing Claude Code and Codex integrations, giving local Cursor agents persistent Stagehand browser tools over MCP/stdio.

what changed

• Adds a runnable @cursor/sdk integration using Cursor's local runtime.
• Mounts the Stagehand facade as the only enabled MCP tool surface.
• Preserves one browser session across run, snapshot, and screenshot.
• Uses an isolated temporary workspace and disables ambient Cursor settings.
• Forwards only STAGEHAND_* and BROWSERBASE_* variables to the MCP child.
• Cancels active runs on SIGINT and SIGTERM and cleans up all temporary resources.
• Adds unit tests, setup documentation, an integration guide, navigation, and a Cursor icon.
• Verifies the integration with a live Browserbase smoke test.

---

Summary by cubic

Adds a Cursor SDK integration so a local @cursor/sdk agent or the Cursor CLI can use persistent Stagehand browser tools over MCP/stdio. Previously Cursor was unsupported; now one agent and one facade share one browser across run, snapshot, and screenshot, with signal handling that preserves CLI exit signals.

• Introduces packages/integrations/cursor (@browserbasehq/stagehand-integrations-example-cursor-facade) that launches a local Cursor agent with the Stagehand facade as the only MCP tool; ships .cursor/mcp.json so the agent CLI can mount the same facade.
• Isolates runs in a temp workspace, disables Cursor setting sources, stores the local agent store in-workspace, and forwards only non-empty STAGEHAND_*/BROWSERBASE_* env vars to the MCP child; never forwards CURSOR_API_KEY.
• Keeps one browser session for the full run; defaults the model to composer-2.5 (override with CURSOR_STAGEHAND_MODEL) and clarifies Browserbase vs. local Chrome selection.
• On SIGINT/SIGTERM, cancels the active run, always cleans up the agent and workspace, surfaces explicit errors for interrupted/failed/empty-text runs, and re-emits the original signal so the CLI exits with the same signal status.
• Adds v4/integrations/cursor.mdx, overview/nav updates, and a Cursor icon; documents CLI usage and headless approvals.
• Adds unit tests for env allowlisting, agent options, prompt shaping, signal handling, cleanup, error paths, and CLI failure handling (signal re-raise and exit code).

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: 0e9c705

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/​@​cursor/​sdk@​1.0.28

View full report

[cubic-dev-ai]

All reported issues were addressed across 13 files

Architecture diagram

sequenceDiagram
    participant CLI as CLI Entry (agent.ts main)
    participant RC as runCursor()
    participant CursorSDK as Cursor Agent (@cursor/sdk)
    participant MCPChild as Stagehand Facade MCP Server
    participant StagehandCore as Stagehand Core (Browser Tools)
    participant Browser as Browser (local/Browserbase)
    participant FS as Temp Workspace

    Note over CLI,FS: Cursor SDK Integration - Runtime Architecture

    CLI->>RC: runCursor(instruction)
    RC->>FS: mkdtemp (isolated workspace)
    RC->>RC: buildCursorAgentOptions(allowlist env STAGEHAND_*/BROWSERBASE_*)
    RC->>CursorSDK: Agent.create(options)
    CursorSDK->>CursorSDK: Local store in workspace, settingSources=[], tools=["mcp"]
    CursorSDK->>MCPChild: spawn stdio (facade server path, filtered env)
    MCPChild->>StagehandCore: Initialize shared browser session

    RC->>CursorSDK: agent.send(prompt + FACADE_AGENT_INSTRUCTIONS)
    CursorSDK->>CursorSDK: Agent loop (model inference hosted by Cursor)
    CursorSDK->>MCPChild: run "run" tool (browser task)
    MCPChild->>StagehandCore: Execute browser automation
    StagehandCore->>Browser: Navigate/interact via extension
    Browser-->>StagehandCore: Page state
    StagehandCore-->>MCPChild: run result
    MCPChild-->>CursorSDK: tool result

    CursorSDK->>MCPChild: run "snapshot" tool (same session)
    MCPChild->>StagehandCore: Get current snapshot
    StagehandCore->>Browser: Read DOM/state
    Browser-->>StagehandCore: Snapshot data
    StagehandCore-->>MCPChild: snapshot result
    MCPChild-->>CursorSDK: tool result

    CursorSDK->>MCPChild: run "screenshot" tool (same browser)
    MCPChild->>StagehandCore: Capture screenshot
    StagehandCore->>Browser: Render capture
    Browser-->>StagehandCore: Screenshot image
    StagehandCore-->>MCPChild: screenshot result
    MCPChild-->>CursorSDK: tool result

    CursorSDK-->>RC: RunResult (finished)
    alt RunResult error or cancelled
        RC->>RC: Throw descriptive error
    end
    RC->>CLI: Return assistant text

    Note over RC,FS: Shutdown & Cleanup
    RC->>CursorSDK: asyncDispose()
    CursorSDK->>MCPChild: Terminate stdio process
    MCPChild->>StagehandCore: Release browser session
    RC->>FS: rm -rf workspace

    rect rgb(50,50,50)
        Note over RC,CursorSDK: Signal handling (SIGINT/SIGTERM)
        CursorSDK->>RC: Signal received
        RC->>CursorSDK: activeRun.cancel()
        CursorSDK-->>RC: Run cancelled
        RC->>RC: Throw "Cursor run interrupted"
    end

Loading

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

Re-trigger cubic</sub>

[cubic-dev-ai]

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

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

Re-trigger cubic</sub>

[cubic-dev-ai]

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

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

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

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

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

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>