feat(sdk-ts): env overrides for extension asset paths

[miguelg719]

Small targeted change: STAGEHAND_EXTENSION_ARCHIVE_PATH / STAGEHAND_EXTENSION_DIRECTORY_PATH env overrides for the two derived asset constants.

Why: bundlers that inline the SDK re-anchor import.meta.url, breaking the derived paths. Hit twice in the Eve integration: eve build (nitro bundle missing the zip → 'Failed to upload the Stagehand extension') and now eve dev (authored-module bundle → CDP Extensions.loadUnpacked fails with 'File path cannot be resolved' for local browsers). The env override is the standard escape hatch; the Eve example sets them from a tiny wrapper that resolves the real installed paths outside any bundle.

Gate: build, typecheck, 186/186 unit tests.

---

Summary by cubic

Adds env overrides for extension asset paths in @browserbasehq/stagehand so bundled builds can point to real assets. Trims whitespace so empty override values are ignored.

• New Features
  • Support STAGEHAND_EXTENSION_ARCHIVE_PATH and STAGEHAND_EXTENSION_DIRECTORY_PATH via process.env, falling back to import.meta.url-derived paths when unset or blank.

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: c614548

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 changesets to release 5 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-integrations	Patch
@browserbasehq/stagehand-integrations-example-eve-facade	Patch
@browserbasehq/stagehand-integrations-example-mastra-facade	Patch
@browserbasehq/stagehand-integrations-example-vercel-ai-facade	Patch

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

[cubic-dev-ai]

All reported issues were addressed across 2 files

Architecture diagram

sequenceDiagram
    participant Caller as Host Code
    participant Assets as extensionAssets.ts
    participant Env as process.env
    participant FS as File System

    Note over Caller,FS: NEW: Resolve extension asset paths with env overrides

    Caller->>Assets: get extension asset path (archive or directory)
    Assets->>Env: Check corresponding STAGEHAND_EXTENSION_*_PATH
    alt Env var set (e.g., bundler inlined, import.meta.url broken)
        Env-->>Assets: real path
        Assets-->>Caller: return env override path
    else Env var not set
        Env-->>Assets: undefined
        Assets->>Assets: derive from import.meta.url (packageRoot)
        Assets-->>Caller: return derived path (default)
    end

    Note over Caller,FS: Same logic for both ARCHIVE and DIRECTORY constants

Loading

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

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 1 file (changes from recent commits).

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

Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Confidence score: 4/5

• In packages/sdk-ts/src/extensionAssets.ts, the new environment-override logic (including the nonEmpty empty/whitespace-as-unset edge case) is untested, so a subtle regression in override precedence or value parsing could slip through and cause incorrect extension asset resolution at runtime — add focused unit tests for unset, empty, whitespace-only, and valid env values plus precedence behavior.

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="packages/sdk-ts/src/extensionAssets.ts">

<violation number="1" location="packages/sdk-ts/src/extensionAssets.ts:9">
P2: The new env-override behavior (including the `nonEmpty` edge-case handling that treats empty/whitespace-only values as unset, which was a dedicated fix commit) has no unit-test coverage. The existing 186 tests pass but none import `extensionAssets` or set these env vars, so the override path, the trim fallback, and the module-load-time env read can regress silently. Consider adding focused tests covering: env set → uses override, env unset → derived path, env empty/whitespace-only → derived path, and env with surrounding whitespace → trimmed value.</violation>
</file>

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

Re-trigger cubic</sub>

[mintlify]

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

Project	Status	Preview	Updated (UTC)
stagehand	🟢 Ready	View Preview	Aug 10, 2026, 8:45 AM

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