feat: Browserbase node UX changes

[alexander-gekov]

Summary

• New v3 node layout (typeVersion 3, gated with @version range conditions):
  • Collapsed Resource + Operation into a single Action dropdown (Run an Agent / Fetch a Webpage / Search the Web).
  • Renamed the agent action to Run an Agent (internal value unchanged).
  • Moved the top-level Model (driver) field above URL / Instruction.
  • Grouped Mode, Agent Model, Model Source and advanced settings into a single Model Options collection (no more confusing "agent within an agent" at the top level).
• Tooltips instead of placeholder callouts: removed the empty "Mode Info" / "Model Info" notice callouts and folded their guidance into field tooltips, with docs links for picking a mode and the Stagehand model evals.
• Per-provider BYOK model keys: replaced the single Model API Key credential field with provider-specific keys (Anthropic / OpenAI / Google). The node resolves the key matching the selected model's provider, with a fallback to the legacy modelApiKey (kept as deprecated) so existing credentials keep working.
• Node description added for the Nodes panel / AI node search.

Backward compatibility

• version: [2, 2.1, 3]. v2 / v2.1 nodes keep their original UI and parameters; the new layout is gated to v3+.
• UI gates use _cnd range conditions (gte: 3 / lt: 3) that mirror the >= 3 checks in execute(), so the display and parameter-reading logic stay in sync and future minor bumps (v3.1, v2.2) won't desync.
• Credential change is additive (new optional fields + legacy fallback), so existing credentials resolve correctly.

Open questions for Browserbase

• Is there a dynamic model-list endpoint? The model lists are currently hardcoded per mode.
• Are mixed-provider BYOK sessions supported (different providers for driver vs. agent model)?
• Newer models (e.g. openai/gpt-5.5, anthropic/claude-opus-4-8) ?

Test plan

• v3 node: Action dropdown switches fields correctly; Model + Model Options render as expected
• v2 / v2.1 existing workflows still render and execute unchanged (no broken/empty node)
• Tooltips render with working links; Mode / Model Source explanations clear
• BYOK: per-provider keys persist after save + refresh and resolve to the right provider
• Gateway default (no keys set) still works for Search / Fetch / Agent

[shubh24]

Review: model lists & v3 fallback

Reviewed against the current Stagehand source (AVAILABLE_CUA_MODELS in packages/core/lib/v3/types/public/agent.ts:458 and resolveModel() in packages/core/lib/modelUtils.ts:61). A few things to address before merge.

🔴 Must-fix

1. Driver-model Gemini 3 IDs are wrong (missing -preview).
The top-level Model dropdown lists google/gemini-3-flash and google/gemini-3-pro, but the canonical Stagehand IDs are google/gemini-3-flash-preview and google/gemini-3-pro-preview. Because the Agent Model falls back to the driver Model when unset, the default v3 path (google/gemini-3-flash + CUA) sends a string that isn't in AVAILABLE_CUA_MODELS, so resolveModel() returns isCua: false and the agent silently won't run in CUA mode. Please reconcile to the canonical IDs.

2. Agent-model fallback can pick a mode-incompatible model.
agentModel = modelCua || driverModel means that if a user picks a non-CUA driver model (e.g. openai/gpt-4o) + CUA mode without expanding Model Options, a non-CUA model is sent as the agent model. Either validate the resolved agent model against the selected mode, or don't fall back across incompatible modes.

🟡 Should-fix

3. Node model lists are behind Stagehand — sync to AVAILABLE_CUA_MODELS.
The dropdowns are stale relative to Stagehand's current CUA list (Stagehand is the up-to-date source of truth; the node is what's behind). Stagehand already supports models missing here: openai/gpt-5.4, openai/gpt-5.4-mini, openai/gpt-5.5, anthropic/claude-opus-4-8, anthropic/claude-opus-4-5-20251101, anthropic/claude-fable-5, microsoft/fara-7b. This also answers the open question in the PR description — yes, gpt-5.5 and claude-opus-4-8 are supported. Recommend mirroring AVAILABLE_CUA_MODELS.

Note: because the node hardcodes this list independently, it will drift again on every Stagehand model addition. That's the real motivation behind the "dynamic model-list endpoint?" open question — the durable fix is exposing the CUA list via the API so dropdowns can populate dynamically. There is no such endpoint today (and Vercel AI Gateway's getAvailableModels() isn't CUA-filtered, so it can't back the Agent Model dropdown as-is).

4. Inconsistent Haiku ID.
modelHybrid uses anthropic/claude-haiku-4-5-20251001 (dated) while modelCua uses anthropic/claude-haiku-4-5 (undated). Both are valid in the SDK — pick one for consistency.

5. modelHybrid options aren't alphabetized.
Likely trips the n8n ESLint rule node-param-options-type-unsorted-items (the CUA/DOM/driver lists are sorted). Worth running npm run lint before merge.

[shubh24]

Follow-up: re-reviewed after the latest two commits

Thanks for the quick turnaround — 21f26ac (Gemini -preview IDs) and 2d110d8 (CUA list sync + fallback guard) cleanly resolve all 5 points from my earlier review. I verified the new CUA_MODEL_OPTIONS is an exact set match to Stagehand's canonical AVAILABLE_CUA_MODELS (19/19), so the new guard is sound. 🎉

Reading the full execute path (not just the diff), three things stood out — two correctness bugs and one UX call.

🔴 Bug 1 — resolveModelApiKey falls back to the legacy key regardless of provider

return ((perProvider[provider] as string) || (credentials.modelApiKey as string) || '').trim();

If a credential was saved before per-provider keys (so only the legacy modelApiKey is set, e.g. an OpenAI key) and the user then selects an Anthropic model with modelSource = userProvidedKey, this returns the legacy OpenAI key and ships it as x-model-api-key for an Anthropic model → upstream 401. The if (!modelApiKey) throw … check doesn't catch it because the string is non-empty, just wrong-provider. Suggest only using the legacy fallback when it matches the selected provider (or dropping it for non-matching providers).

🔴 Bug 2 — Hybrid mode has the same silent-skip hole the CUA guard just fixed

The new guard is mode === 'cua' only:

if (mode === 'cua' && !CUA_MODELS.has(agentModel)) { … }

But agentModel = modelOptions.modelHybrid || driverModel has the identical fallback, and the Hybrid dropdown says its model "must support coordinate actions." So driver = gpt-4o-mini + hybrid + no override sends a possibly-incompatible model with no validation — the exact failure mode you just closed for CUA, one mode over. Worth extending the guard to Hybrid (against the coordinate-capable set).

🟡 UX (not a code defect) — default mode is CUA, but two driver options can't do CUA

mode defaults to cua, and the driver Model dropdown offers gpt-4o / gpt-4o-mini, neither of which is in CUA_MODELS. So a user who picks the familiar "GPT-4o" and changes nothing else now hits a hard error from the new guard. The error message is clear and this is strictly better than the old silent failure — flagging it only as a likely-support-ticket UX edge. Options: drop non-CUA models from the driver list, or surface the mode requirement in the dropdown.

I'd treat Bug 1 and Bug 2 as merge blockers; the UX item is your call.