Add multiagent driver package

[pirate]

Summary

• add a new packages/multiagent workspace package and multiagent CLI for running one or more agent harnesses against shared browser and MCP tool configurations
• split the runtime into isolated actors for browser lifecycle, MCP servers/tool adapters, agent harness sessions, and the top-level driver/orchestrator
• implement the initial harness, toolset, and browser-mode adapters and document the full support matrix, config surface, and development workflow in the package README

What's in this PR

• new packages/multiagent package with BrowserSession, MCPServer, AgentSession, and MultiAgentDriver
• CLI entrypoints for multiagent run and the package's internal stdio MCP server mode
• harness adapters for Claude Code, Codex, Gemini CLI, OpenCode, Browser Use, and Stagehand
• explicit agent-browser harness rejection with a clear error because upstream is a browser runtime/CLI rather than an LLM harness loop
• tool adapters for chrome-devtools-mcp, playwright-mcp, agent-browser-mcp, Browser Use MCP, Stagehand agent tools, and Understudy tools
• browser connection modes for either attaching to a provided CDP endpoint or launching a local Chromium instance via Puppeteer and reconnecting over CDP
• unit tests covering the driver, browser session lifecycle, and harness/tool adapter behavior
• a detailed package README covering architecture, state ownership, lifecycle, usage, config, support matrix, and development setup

Architecture

This package is intentionally split into a few small state-owning services rather than one large runner:

• BrowserSession owns the connected browser instance, whether that means attaching to an existing CDP URL or launching local Chromium
• MCPServer owns one tool server at a time, including process lifecycle, tool discovery, and direct tool calls for internal adapters
• AgentSession owns per-harness invocation state, message history, and the set of attached MCP servers exposed to that harness
• MultiAgentDriver composes those services, fans the task out across one or more configured harnesses, and collects per-agent results

That split keeps browser state, tool state, and harness state isolated so we can add more harnesses/toolsets without turning the runtime into shared mutable state.

Supported surface in this PR

Harnesses

• claude-code
• codex
• gemini-cli
• opencode
• browser-use
• stagehand
• agent-browser is intentionally treated as unsupported as a harness and returns a descriptive error

Toolsets

• playwright
• chrome-devtools
• agent-browser
• browser-use
• stagehand-agent
• understudy

Browser modes

• cdpUrl: attach to an existing browser over CDP
• no cdpUrl: launch local Chromium with Puppeteer, then attach the loops/tools over CDP

Verification

Passing

• pnpm --filter @browserbasehq/multiagent run test

Failing on current main baseline outside this diff

• pnpm --filter @browserbasehq/multiagent run typecheck
• pnpm --filter @browserbasehq/multiagent run build

Both currently fail because packages/core/lib/v3/launch/browserbase.ts no longer satisfies SessionCreateParams on main (projectId is now required there). This PR does not touch that code path.

Smoke coverage performed while building the package

• opencode + playwright + local Chromium against example.com
• browser-use + local Chromium against example.com
• gemini-cli path verifying that missing auth is surfaced cleanly through the driver
• agent-browser path verifying the intentional explanatory unsupported-harness error

Notes

• I restacked multiagent-driver onto main before opening this PR so the diff is isolated to the multiagent package instead of inheriting the unrelated server-v4-understudy-routes history.
• packages/multiagent/README.md is intended to stay current with support/config/runtime changes and documents the architecture in detail.

---

Summary by cubic

Adds the @browserbasehq/multiagent package and multiagent CLI to run one or more agent harnesses against a shared browser session and MCP tool servers. The runtime is split into isolated actors for browser, tools, and per-agent sessions with a driver orchestrator.

• New Features

  • New CLI: multiagent run and multiagent mcp-server <stagehand-agent|understudy>.
  • Core services: BrowserSession, MCPServer, AgentSession, MultiAgentDriver.
  • Harnesses: claude-code, codex, gemini-cli, opencode, browser-use, stagehand.
  • Tool adapters: playwright, chrome-devtools, agent-browser, browser-use, stagehand-agent, understudy.
  • Browser modes: attach via cdpUrl or launch local Chromium via puppeteer-core and reconnect over CDP.
  • Tests for driver/browser/harness-tool behavior and a README with architecture, config, and support matrix.

• Dependencies

  • Adds @modelcontextprotocol/sdk, @playwright/mcp, chrome-devtools-mcp, agent-browser, agent-browser-mcp, puppeteer-core (see pnpm-lock.yaml).

^{Written for commit 63941e8. Summary will update on new commits. Review in cubic}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 63941e8

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