feat(llm): support claude-fable-5 (structured outputs, adaptive thinking, refusal fallback)

[miguelg719]

Why

Claude Fable 5 breaks Stagehand today in three independent ways: it rejects forced tool use (400 tool_choice forces tool use is not compatible with this model), which kills both act/extract/observe (forced json tool) and the agent's final done call; it rejects sampling parameters like temperature; and its safety classifiers can decline a turn (stop_reason: "refusal") with no retry story. Separately, the hybrid/DOM agent path has never sent any Anthropic thinking config, so adaptive-thinking models ran with thinking off.

What changed

• @ai-sdk/anthropic 2.0.57 → 2.0.81 (v5-compatible line, within ^2.0.34; floor raised). The provider's capability table now knows fable-5/opus-4-7/4-8: the existing structuredOutputMode: "auto" resolves to native output_config.format instead of the forced json tool, rejected sampling params are stripped, and max_tokens is sized from the real 128k limit — zero code changes for the primitives.
• New lib/v3/llm/anthropicOptions.ts — one capability table for Anthropic agent models (adaptive-thinking set, xhigh-capable set, fable-5 constants, rejectsForcedToolUse).
• Adaptive thinking on the hybrid/DOM agent path via typed provider options on both streamText call sites. Effort defaults to a shared medium on both agent paths and is overridable per client via thinkingEffort in the agent model config (plumbed through V3AgentHandler so the typed option now works on the hybrid path too); ThinkingEffort gains xhigh (clamped to high on models that reject it), and "none" opts out of thinking on both paths. The CUA client drops its inline model list and effort default for the shared ones.
• Server-side refusal fallback: fable-5 requests carry fallbacks: [{model: "claude-opus-4-8"}] as a typed provider option on agent and act/extract/observe calls; the provider adds the server-side-fallback-2026-06-01 beta header automatically and reports attribution via usage.iterations.
• Final done call: consults rejectsForcedToolUse() and goes straight to toolChoice: "auto" on fable-5 (forced tool choice is incompatible with always-on thinking); a narrow /tool_choice/i catch remains as a safety net for unknown models.
• Registration: claude-fable-5 in AgentProvider, AVAILABLE_CUA_MODELS, and the public-api test.

Not in scope: CUA-mode (raw @anthropic-ai/sdk 0.39.0) fallback wiring — the pinned SDK predates the fallbacks param; a refusal there surfaces as stop_reason: "refusal" without retry.

Tests

• pnpm typecheck and build:esm green; 34/34 unit tests (12 new covering the capability helpers: adaptive set, xhigh clamping, effort precedence, fallbacks gating, forced-tool gate).
• Offline request-body capture (mock fetch, 2.0.81): generateObject on fable-5 sends output_config.format = {type: "json_schema", …, additionalProperties: false} + structured-outputs-2025-11-13 beta with no tools/tool_choice; generateText with the agent options sends thinking: {"type":"adaptive"}, output_config: {"effort":"xhigh"}, fallbacks: [{"model":"claude-opus-4-8"}] and the effort-2025-11-24,server-side-fallback-2026-06-01 betas.
• Not yet run against the live API from this machine — worth one live pass (extract + DOM/hybrid agent on fable-5) before un-drafting.

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: d32cdc1

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server-v3	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cubic-dev-ai]

1 issue found across 11 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.
Tip: cubic used a learning from your PR history. Let your coding agent read cubic learnings directly with the cubic MCP.

Fix all with cubic | Re-trigger cubic</sub>

[miguelg719]

@cubic-dev-ai

[cubic-dev-ai]

@cubic-dev-ai

@miguelg719 I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

No issues found across 14 files

Confidence score: 5/5

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

Architecture diagram

sequenceDiagram
    participant App as Application
    participant V3A as V3AgentHandler
    participant LLM as "AISdkClient / LLMClient"
    participant V3H as "V3AgentHandler (execute/stream)"
    participant HandleDone as handleDoneToolCall
    participant CUA as AnthropicCUAClient
    participant Opts as "anthropicOptions.ts"
    participant SDK as "@ai-sdk/anthropic"
    participant API as "Anthropic API"

    Note over App,API: Claude Fable-5 Request Path — Hybrid/DOM Agent

    App->>V3A: init agent with model "claude-fable-5"
    V3A->>V3A: AgentProvider maps model -> "anthropic"

    Note over V3A,Opts: Agent execute/stream loops (per-turn)
    loop execute loop or stream loop
        V3A->>Opts: buildAgentProviderOptions()
        Opts->>Opts: anthropicAdaptiveThinkingOptions()
        opt Fable 5 (adaptive-capable model)
            Opts->>Opts: return {thinking:{type:"adaptive"}}
            alt effort configured (explicit or STAGEHAND_THINKING_EFFORT)
                Opts->>Opts: resolveAdaptiveEffort()
                alt effort == "xhigh"
                    opt model rejects xhigh (sonnet-4-6)
                        Opts->>Opts: clamp to "high"
                    end
                    Opts-->>Opts: return "xhigh" or clamped value
                end
            end
        end
        Opts->>Opts: anthropicFallbacksOptions()
        opt Fable 5 (fallback model set)
            Opts->>Opts: return {fallbacks:[{model:"claude-opus-4-8"}]}
        end
        Opts-->>V3A: merged providerOptions

        V3A->>LLM: streamText({ providerOptions, ... })
        LLM->>SDK: pass anthropic provider options
        SDK->>SDK: strip temperature (rejected by Fable 5)
        SDK->>API: POST (thinking+effort+fallbacks+betas)
        Note over SDK,API: beta headers: effort-2025-11-24, server-side-fallback-2026-06-01
        API-->>SDK: response (maybe refusal -> fallback to opus-4-8)
        SDK->>SDK: include usage.iterations for fallback attribution
        SDK-->>LLM: result
        LLM-->>V3A: response.messages
    end

    Note over App,HandleDone: Final "done" Tool Call (end of agent loop)

    V3A->>HandleDone: handleDoneToolCall(model, messages)
    HandleDone->>Opts: rejectsForcedToolUse(modelId)
    alt Fable 5 (always-on thinking)
        Opts-->>HandleDone: true
        HandleDone->>HandleDone: set toolChoice: "auto" (instead of forced "done" tool)
    else Other models
        Opts-->>HandleDone: false
        HandleDone->>HandleDone: set toolChoice: {type:"tool", toolName:"done"}
    end

    HandleDone->>Opts: anthropicFallbacksOptions(modelId)
    opt Fable 5
        Opts-->>HandleDone: fallbacks config
        HandleDone->>HandleDone: merge into providerOptions.anthropic
    end

    HandleDone->>SDK: generateText({ toolChoice, providerOptions, ... })
    SDK->>API: POST (tools+toolChoice or auto+fallbacks)
    alt No tool call (plain text answer)
        API-->>SDK: response without tool use
        SDK-->>HandleDone: result
        HandleDone-->>V3A: return plain text answer
    else Tool call with "done"
        API-->>SDK: response with done tool
        SDK-->>HandleDone: result
        HandleDone-->>V3A: return done result
    end

    Note over App,API: Structured Output Path (act/extract/observe)

    App->>LLM: act/extract/observe call
    LLM->>LLM: inferProviderName("claude-fable-5") -> "anthropic"
    LLM->>LLM: set structuredOutputMode: "auto"
    LLM->>Opts: anthropicFallbacksOptions(modelId)
    opt Fable 5
        Opts-->>LLM: fallbacks config
        LLM->>LLM: merge into providerOptions.anthropic
    end
    LLM->>SDK: generateObject({ providerOptions, ... })
    SDK->>SDK: structuredOutputMode: "auto" => output_config.format (native JSON schema)
    Note over SDK: no tools/tool_choice sent — native structured outputs
    SDK->>API: POST (output_config.format + fallbacks)
    API-->>SDK: JSON response
    SDK-->>LLM: result
    LLM-->>App: structured data

    Note over App,CUA: CUA (Computer Use Agent) Path

    App->>CUA: init agent with model "claude-fable-5"
    CUA->>CUA: stripModelProvider() -> "claude-fable-5"
    CUA->>Opts: isAdaptiveThinkingAnthropicModel("claude-fable-5")
    Opts-->>CUA: true
    CUA->>CUA: set thinking = {type: "adaptive"}
    CUA->>Opts: resolveAdaptiveEffort("claude-fable-5", thinkingEffort)
    Opts-->>CUA: effort value (maybe xhigh or clamped)
    CUA->>CUA: set outputConfig = {effort: ...}

    loop CUA tool use cycle
        CUA->>API: POST (thinking adaptive + output_config effort + computer_20251124 tools)
        API-->>CUA: response (tool_use items)
        CUA->>CUA: execute tool, capture screenshots
    end

    Note over App,API: Refusal Handling (any Fable 5 call)

    opt Refusal (stop_reason: refusal)
        API->>SDK: response with fallback attribution in usage.iterations
        Note over SDK,API: API retried on claude-opus-4-8 automatically
        SDK-->>LLM: result (with usage.iterations > 1)
    end

Loading

_{Re-trigger cubic}

[shrey150]

Pre-approving, left some comments if you choose to address - non-blocking