feat(pi): publish the native Stagehand extension as a Pi package

[shrey150]

Pi already registers Stagehand’s three browser tools through the native extension API, but the documented setup requires a monorepo checkout. This packages that extension as @browserbasehq/pi, with the official pi.extensions manifest and pi-package catalog keyword, and makes pi install npm:@browserbasehq/pi the documented install path.

The package bundles the private Core facade and keeps the public Stagehand SDK external so its extension assets remain intact. Includes Changesets, release builds, package metadata, README, and public guide updates. The existing Pi behavior PRs (#2794, #2926, #2927) remain separate.

Release prerequisite: configure npm trusted publishing for @browserbasehq/pi from browserbase/stagehand / .github/workflows/release.yml. The included changeset produces the first 0.1.0 release. The docs explicitly mark the npm install as unavailable until publication and retain a source install.

E2E Test Matrix

Command / flow	Observed output	Confidence / sufficiency
turbo run build --filter @browserbasehq/pi	5 tasks passed; bundled extension emitted	Build and dependency boundary
Pi typecheck and unit tests	Passed; 3 tests passed	Host tool registration and lifecycle registration
Release helper tests	17 tests passed	Release validation and changelog helpers
Frozen lockfile validation	Passed with pnpm 11.10.0	Manifest/lock consistency
Packed package installed in a clean npm consumer and registered with real pi install --approve -l	Three tools registered without the private Core package	Installable package boundary
Packed native tools against Browserbase / example.com	Correct title, persistent snapshot state, JPEG returned, session shutdown completed	Real browser execution through the packaged extension; no full Pi model-loop benchmark

Documentation validation: a combined snapshot of all nine updated integration guides passed mint validate and mint broken-links --check-anchors --check-redirects --check-snippets.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
stagehand	🟢 Ready	View Preview	Sep 17, 2026, 10:33 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[changeset-bot]

🦋 Changeset detected

Latest commit: 16e28a2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@browserbasehq/pi	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cubic-dev-ai]

1 issue found across 11 files

Confidence score: 4/5

• scripts/release/consolidate-changelogs.ts lacks regression coverage for Pi package changelogs, so future changes could fail to consolidate the Pi extension heading unnoticed; add a release-helper test that runs a Pi package through the package list and verifies the heading is consolidated.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="scripts/release/consolidate-changelogs.ts">

<violation number="1" location="scripts/release/consolidate-changelogs.ts:9">
P2: The new Pi changelog entry has no regression coverage. Add a release-helper test that exercises a Pi package changelog through this package list and verifies the `Pi extension` heading is consolidated.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Dev as Developer
    participant Pi as Pi Coding Agent
    participant Pkg as @browserbasehq/pi Package
    participant Core as Private Core Facade
    participant SDK as Stagehand SDK
    participant Browser as Browser Session

    Note over Dev,Pi: Package Installation Flow (npm)
    
    Dev->>Pi: pi install npm:@browserbasehq/pi
    Pi->>Pkg: Load package from npm registry
    Pkg->>Pkg: Read pi.extensions manifest
    Pi->>Pkg: Register stagehand.mjs extension
    
    Note over Pkg,SDK: Runtime Architecture
    
    Pi->>Pkg: Invoke run/snapshot/screenshot tool
    Pkg->>Core: Call bundled facade implementation
    Core->>SDK: Create Stagehand client
    SDK->>Browser: Launch persistent browser (first call)
    SDK->>Browser: Execute browser action
    Browser-->>SDK: Result (snapshot/state)
    SDK-->>Core: Return result
    Core-->>Pkg: Tool response
    
    Note over Pkg,SDK: Bundle Boundaries
    
    alt Source install (development)
        Dev->>Pkg: Build from monorepo via turbo
        Pkg->>Pkg: tsdown bundles Core facade only
        Note over Pkg,SDK: SDK remains external dependency
    end
    
    Note over Pi,Browser: Session Lifecycle
    
    Pi->>Pkg: Session shutdown
    Pkg->>SDK: Close browser connection
    SDK->>Browser: Terminate session
    
    Note over Dev,Pi: Package Publication (first release)
    
    Dev->>Pkg: Run release workflow
    Pkg->>Pkg: Changeset creates 0.1.0 version
    Pkg->>Pkg: Build package (prepack)
    Pkg-->>Pi: Publish to npm registry
    
    alt Trusted publishing configured
        Pkg-->>Dev: Package available for pi install
    else Trusted publishing pending
        Pkg-->>Dev: Package unavailable, use source install
    end

Loading

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The new Pi changelog entry has no regression coverage. Add a release-helper test that exercises a Pi package changelog through this package list and verifies the Pi extension heading is consolidated.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/release/consolidate-changelogs.ts, line 9:

<comment>The new Pi changelog entry has no regression coverage. Add a release-helper test that exercises a Pi package changelog through this package list and verifies the `Pi extension` heading is consolidated.</comment>

<file context>
@@ -5,6 +5,10 @@ import { pathToFileURL } from "node:url";
 const rootChangelogPath = path.join(repositoryRoot, "CHANGELOG.md");
 const packageChangelogs = [
+  {
+    label: "Pi extension",
+    path: path.join(repositoryRoot, "packages/integrations/pi/CHANGELOG.md"),
+  },
</file context>