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 an MCP/stdio server so OpenCode sessions share one persistent browser across run, snapshot, and screenshot. Previously OpenCode was unsupported; now a local SDK example and optional CLI config provide these tools with strict isolation.

• 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 on completion or SIGINT/SIGTERM; the MCP child receives only STAGEHAND_* and BROWSERBASE_* env (provider credentials stay in OpenCode).

• Enables exactly stagehand_run, stagehand_snapshot, and stagehand_screenshot; all other tools are disabled and denied.

• OPENCODE_MODEL is optional for selecting the OpenCode model; Stagehand JavaScript helpers still use STAGEHAND_MODEL_* credentials (docs clarify provider tokens are not reused). The included opencode.json mounts the facade for the opencode CLI; note the CLI forwards its shell env to the MCP child, unlike the SDK example’s allowlist.

• Tests cover env allowlist, tool permissions, session lifecycle, interruption, and cleanup. Docs add v4/integrations/opencode, update the overview, and include an OpenCode icon. 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 9597ff8. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 9597ff8

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>