feat(integrations): add Flue integration

[antonvishal]

Why

Add a Flue example alongside the existing Eve and Pi native integrations, giving a Flue agent persistent Stagehand browser tools in-process without an MCP bridge.

What changed

Adds a runnable @flue/runtime integration using Flue's Node start / init / dispatch / read loop.
Binds the Stagehand facade as native run, snapshot, and screenshot tools on one shared browser session.
Validates tool arguments with the canonical facade Zod schemas; Flue's Valibot input is only the host adapter defineTool requires.
Writes screenshots to a temporary file because Flue's tool loop is text-only.
Aborts the Flue submission on SIGINT and SIGTERM, then closes the browser and stops the runtime.
Adds unit tests, setup documentation, an integration guide, navigation, and a Flue icon.

---

Summary by cubic

Adds a native Flue integration that exposes Stagehand’s run, snapshot, and screenshot tools over one persistent browser session without an MCP bridge. For Flue, screenshot now returns a temporary file path and MIME type instead of binary because Flue’s tool loop is text-only.

• New example package @browserbasehq/stagehand-integrations-example-flue-facade:
  • src/session.ts lazily creates and shares one browser, checks health, and cleans up; src/run-agent.ts aborts on SIGINT/SIGTERM and closes the browser and runtime.
  • Tools use the canonical facade Zod schemas and satisfy Flue’s defineTool inputs with valibot; inputs are strict (no extra properties) and run now requires exactly one of code or actions.
  • src/artifacts.ts writes screenshots to a temp directory and returns { path, mimeType }.
  • tests/tools.test.ts cover input validation, tool wiring, and a full Flue agent loop via a faux provider.
• Docs and assets:
  • Adds /v4/integrations/flue with quickstart and configuration; updates navigation and adds a Flue icon.
  • Mentions Flue in integrations overview and best-practices; notes that CrewAI and Flue return screenshot file paths.
• Workspace/build:
  • Adds @flue/runtime and valibot to the catalog, @earendil-works/pi-ai for tests, updates pnpm-lock.yaml, and wires typecheck in turbo.json.
• Try it:
  • Build: pnpm exec turbo run build --filter @browserbasehq/stagehand-integrations
  • Run: pnpm --filter @browserbasehq/stagehand-integrations-example-flue-facade start "Open https://example.com and report the page title."
  • Requires Node 24+ and pnpm 11.10.0.

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: cd3b493

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>