fix(core): gracefully handle runtimes that omit AsyncLocalStorage.enterWith() (fixes #2055)

[octo-patch]

Fixes #2055

Problem

Since v3.2.0, FlowLogger.init() calls AsyncLocalStorage.enterWith() to set the session-wide logging context. Cloudflare Workers intentionally omits enterWith() from their AsyncLocalStorage implementation — calling it throws asyncLocalStorage.enterWith() is not implemented, which crashes Stagehand immediately during init() before any browser interaction occurs.

Solution

Wrap the enterWith() call in a try/catch. If the runtime does not support enterWith(), we fall through silently. The FlowLoggerContext is still created and returned, so it can be stored by the caller (this.flowLoggerContext in v3.ts). All other ALS usage inside FlowLogger already uses loggerContext.run() (in runWithLogging(), withContext(), logCdpEvent(), etc.), which is supported everywhere — so the logging pipeline continues to work through the explicit-context path on runtimes without enterWith().

Testing

Added a unit test that simulates a runtime without enterWith() (by temporarily setting AsyncLocalStorage.prototype.enterWith = undefined) and asserts that FlowLogger.init() completes without throwing and returns a valid context.

✓ FlowLogger.init() does not throw when enterWith() is not implemented (e.g. Cloudflare Workers)

All existing flowlogger unit tests continue to pass.

---

Summary by cubic

Fixes #2055. Prevents crashes on runtimes that omit AsyncLocalStorage.enterWith() (e.g., Cloudflare Workers) by safely initializing FlowLogger. Logging continues via loggerContext.run() paths.

• Bug Fixes
  • Wrap enterWith() in try/catch in FlowLogger.init(); fall through when missing.
  • Add a unit test that simulates missing enterWith() and verifies init succeeds and returns a valid FlowLoggerContext.

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: 7211ad5

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]

No issues found across 2 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant S as Stagehand / Caller
    participant FL as FlowLogger
    participant ALS as AsyncLocalStorage
    participant Bus as Event Bus

    Note over S, ALS: Initialization Flow (v3.ts)

    S->>FL: init(sessionId, eventBus)
    FL->>FL: Create FlowLoggerContext (ctx)

    rect rgb(240, 240, 240)
        Note right of FL: NEW: Guard against restricted runtimes
        alt Runtime supports enterWith() (e.g. Node.js)
            FL->>ALS: enterWith(ctx)
            ALS-->>FL: Context globally set for current execution
        else Runtime omits enterWith() (e.g. Cloudflare Workers)
            FL->>ALS: enterWith(ctx)
            ALS-->>FL: THROW: "not implemented"
            FL->>FL: Catch and suppress error
        end
    end

    FL-->>S: Return FlowLoggerContext

    Note over S, ALS: Execution Flow (Post-Init)

    S->>FL: runWithLogging(ctx, task)
    Note right of FL: Explicit context path works even if enterWith() failed
    FL->>ALS: run(ctx, task)
    ALS->>Bus: Emit logging events
    ALS-->>FL: Result
    FL-->>S: Result

Loading