feat(integrations): add Flue integration

[antonvishal]

What

Adds a native Flue integration and eval harness so Flue agents can use one persistent Stagehand browser in-process and run against the shared MCP-backed evaluation surfaces.

Integration

• Adds a runnable @flue/runtime example using the Node start, init, dispatch, and read lifecycle.
• Binds run, snapshot, and screenshot as native Flue tools over one shared browser session.
• Validates browser-tool arguments with the canonical Stagehand facade schemas.
• Writes screenshots to temporary files for Flue text-only tool results.
• Handles interruption and closes the browser and Flue runtime cleanly.
• Adds setup documentation, navigation, and the Flue icon.

Eval harness

• Adds the reusable @browserbasehq/stagehand-integrations-flue-sdk session adapter and uses it from both the example and eval runner.
• Registers the flue harness for stagehand_facade, playwright_mcp, and chrome_devtools_mcp.
• Converts shared MCP tools through Flue's native MCP adapter, preserving input schemas, arguments, and error results.
• Reuses the shared external-harness prompt/result contract, evidence capture, verifier, and observation recorder.
• Maps Flue reasoning, text, tool events, usage, cost, completion state, and browser observations into the shared trajectory format.
• Adds runner, MCP tool adapter, trajectory adapter, and registry tests.

Testing

• pnpm check
• Flue SDK: 1 test passed
• Flue example: 6 tests passed
• Focused eval harness suite: 23 tests passed
• git diff --check
• evals run b:webvoyager --harness flue --tool stagehand_facade -l 1 -t 1 -e browserbase ran and passed
• Flue SDK and focused adapter/runner tests: 8 passed. Evals and Flue SDK typechecks passed.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 58c6876

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.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​flue/​runtime@​2.0.3
	npm/​@​earendil-works/​pi-ai@​0.83.0
	npm/​valibot@​1.4.2

View full report

[cubic-dev-ai]

All reported issues were addressed across 20 files

Architecture diagram

sequenceDiagram
    participant CLI as User CLI
    participant Runner as run-agent.ts
    participant Flue as @flue/runtime
    participant Agent as agent/agent.ts
    participant Tools as Flue Tool Adapters
    participant Facade as StagehandFacadeTools
    participant Browser as Browser Session
    participant FS as Temp Filesystem

    Note over CLI,FS: NEW: Flue Integration Runtime Flow

    CLI->>Runner: pnpm start "Open https://example.com..."
    Runner->>Runner: parse task from argv
    Runner->>Flue: start({ agents: [StagehandAgent] })
    Flue-->>Runner: flue runtime instance
    Runner->>Flue: init(StagehandAgent, { id })
    Flue-->>Runner: agent instance
    Runner->>Flue: agent.dispatch(task)
    Flue->>Agent: StagehandAgent() instructions

    Note over Agent: Returns FLUE_STAGEHAND_INSTRUCTIONS<br/>(includes FACADE_AGENT_INSTRUCTIONS)

    Flue->>Tools: run tool call (code)
    Tools->>Tools: validate with Zod facade schema
    Tools->>Facade: getFacadeTools()
    Facade->>Facade: lazy init session if needed
    Facade->>Browser: launch (local or browserbase)
    Browser-->>Facade: browser instance
    Facade->>Facade: Stagehand.create()
    Facade-->>Tools: tools: { run, snapshot, screenshot }

    Tools->>Facade: tools.run(code)
    Facade->>Browser: execute JavaScript
    Browser-->>Facade: result
    Facade-->>Tools: result object
    Tools->>Tools: stringifyResult()
    Tools-->>Flue: string response

    alt Screenshot tool
        Flue->>Tools: screenshot tool call
        Tools->>Tools: validate with Zod facade schema
        Tools->>Facade: tools.screenshot(input)
        Facade->>Browser: capture page
        Browser-->>Facade: { data: base64, mimeType }
        Facade-->>Tools: image data
        Tools->>FS: writeScreenshotArtifact()
        FS-->>Tools: { path, mimeType }
        Tools-->>Flue: { output: { path, mimeType } }
    end

    alt Unhealthy browser detected
        Tools->>Facade: discardFacadeToolsIfUnhealthy()
        Facade->>Facade: check browser health
        alt Browser closed or unreachable
            Facade->>Facade: discardFacadeTools()
            Facade->>Facade: schedule closeResources()
        end
    end

    Flue-->>Runner: agent.read(receipt)
    Runner->>Runner: output reply.text

    Note over Runner: SIGINT/SIGTERM handling

    alt Interrupt received
        Runner->>Flue: agent.abort()
    end

    Runner->>Agent: agent.abort()
    Runner->>Facade: closeFacadeSession()
    Facade->>Browser: stagehand.close()
    Facade->>Browser: browser.close()
    Runner->>Flue: flue.stop()

Loading

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

Re-trigger cubic</sub>

[cubic-dev-ai]

1 existing issue remains and no new issues found across 5 files (changes from recent commits).

Confidence score: 3/5

• In packages/integrations/flue/agent/tools/screenshot.ts, supplied quality values can be fractional and type: "png" can be accepted even though the facade rounds or ignores them, creating inconsistent screenshot behavior; require integer quality and type: "jpeg" whenever quality is present in both validation paths.

<sub>Requires human review: Auto-approval blocked because this review re-detected 1 unresolved issue already reported by Cubic.

Re-trigger cubic</sub>