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. In Flue, screenshot now returns a temporary file path and MIME type instead of image bytes because Flue’s tool loop is text-only.

• Provides @browserbasehq/stagehand-integrations-example-flue-facade: one lazily created shared browser (src/session.ts), graceful cleanup on SIGINT/SIGTERM (src/run-agent.ts), and Flue’s start/init/dispatch/read loop.
• Tools use the canonical facade schemas; inputs are validated with valibot and are strict (no extra properties). run requires exactly one of code or actions. Screenshots are written to a temp file via src/artifacts.ts and returned as { path, mimeType }.
• Tests (tests/tools.test.ts) cover input validation, tool routing, screenshot artifact writing, and a full Flue agent loop via a faux provider.
• Docs: adds /v4/integrations/flue, icon, and links from overview/best-practices; resolves overview conflicts to include both Flue and fx; notes that CrewAI and Flue return screenshot file paths.
• Workspace/build: adds @flue/runtime, valibot, and @earendil-works/pi-ai to the catalog; wires the new package into pnpm-workspace.yaml, turbo.json, and updates pnpm-lock.yaml.
• Configuration: FLUE_STAGEHAND_MODEL selects the agent model (defaults to openai/gpt-5.6-luna); choose the browser with STAGEHAND_BROWSER and optional BROWSERBASE_API_KEY. Removed BROWSERBASE_PROJECT_ID mention from the Flue README (project ID is optional everywhere).

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: 942ad1e

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>