feat(integrations): add OpenCode SDK integration

[antonvishal]

why

Add an OpenCode SDK example alongside the existing Claude Code and Codex integrations, giving OpenCode sessions persistent Stagehand browser tools over MCP/stdio.

what changed

• Adds a runnable @opencode-ai/sdk integration.
• Mounts the Stagehand facade as the only enabled MCP tool surface.
• Preserves one browser session across run, snapshot, and screenshot.
• Isolates OpenCode configuration and restricts permissions to Stagehand tools.
• Forwards only STAGEHAND_* and BROWSERBASE_* variables to the MCP child.
• Adds unit tests, setup documentation, an integration guide, navigation, and an OpenCode icon.

---

Summary by cubic

Adds an OpenCode SDK integration that mounts the Stagehand facade as a local MCP/stdio server so one OpenCode session keeps a persistent browser across run, snapshot, and screenshot. Previously OpenCode was unsupported; now an SDK example and optional CLI config enable these tools with explicit environment isolation.

• SDK example at packages/integrations/opencode uses @opencode-ai/sdk v2 to start a local server, create one session, prompt with only stagehand_* tools, and clean up; the MCP child receives only STAGEHAND_* and BROWSERBASE_* env (provider creds stay in OpenCode).
• Enables exactly stagehand_run, stagehand_snapshot, and stagehand_screenshot; all other tools are disabled and denied. OPENCODE_MODEL is optional; Stagehand JS helpers still use separate STAGEHAND_MODEL_* credentials.
• Ships a project opencode.json for the opencode CLI; note the CLI forwards its shell env to the MCP child (unlike the SDK example's allowlist).
• Refactors the shared buildAllowlistedEnv to accept an optional env source so the OpenCode example reuses it. Tests cover env allowlist, tool permissions, session lifecycle, interruption, and cleanup.
• Docs add v4/integrations/opencode, the icon, and update the overview to include both OpenCode and fx; the integrations README lists OpenCode. Workspace adds @opencode-ai/sdk and opencode-ai, enables opencode-ai builds, updates turbo.json, and pins lockfile entries.
• No migration required. Requires Node 24+ and pnpm 11.10.0. Build @browserbasehq/stagehand-integrations, authenticate OpenCode or export a provider key, and set STAGEHAND_BROWSER/BROWSERBASE_* for Browserbase.

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: 16174c2

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.

[cubic-dev-ai]

All reported issues were addressed across 13 files

Architecture diagram

sequenceDiagram
    participant CLI as CLI Entry (src/agent.ts)
    participant Runtime as OpenCode Runtime (runOpenCode)
    participant SDK as OpenCode SDK (createOpencodeServer/Client)
    participant Config as OpenCode Config
    participant MCP as Stagehand Facade (stdio-server)
    participant Browser as Browser Session

    Note over CLI,Browser: OpenCode SDK integration - Runtime Flow

    CLI->>Runtime: runOpenCode(instruction)
    Runtime->>Runtime: createRuntimeDirectory()
    Runtime->>Config: buildOpenCodeConfig(facadeServerPath, env)
    Config->>Config: Build allowlisted env (STAGEHAND_*/BROWSERBASE_*)
    Config->>Config: Enable only stagehand_run/snapshot/screenshot tools

    Runtime->>SDK: startOpenCodeRuntime({config, directory, configRoot})
    SDK->>SDK: Create temp config dirs + empty config file
    SDK->>SDK: Set env overrides (XDG_CONFIG_HOME, OPENCODE_CONFIG)
    SDK->>SDK: createOpencodeServer()
    SDK-->>Runtime: Server URL

    Runtime->>SDK: session.create({title})
    SDK-->>Runtime: session ID

    Runtime->>SDK: session.prompt({tools, system, parts})
    SDK->>MCP: Spawn with allowlisted env
    MCP->>Browser: Persistent session across calls

    loop Tool calls (run/snapshot/screenshot)
        MCP->>MCP: Execute model-authored JS
        MCP-->>SDK: Tool results (incl. native MCP images)
    end

    SDK-->>Runtime: Assistant text parts
    Runtime->>Runtime: extractAssistantText()

    alt Successful run
        Runtime-->>CLI: Return assistant text
    else Prompt/creation failure
        Runtime->>Runtime: Throw API error
    end

    Runtime->>SDK: session.delete()
    Runtime->>SDK: server.close()
    Runtime->>Runtime: Remove runtime directory

    Note over CLI,SDK: Signal handling (SIGINT/SIGTERM)
    CLI->>Runtime: Termination signal
    Runtime->>Runtime: Forward to AbortController
    Runtime->>SDK: Abort active request
    Runtime->>SDK: Cleanup (delete session, close, remove dir)

Loading

<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>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 2 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 2 files (changes from recent commits).

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

Re-trigger cubic</sub>

[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/​opencode-ai@​1.18.18
	npm/​@​opencode-ai/​sdk@​1.18.18

View full report