feat(extension): decision-model providers (Clef, Perplexity Decider, OpenAI Decisions)

[miguelg719]

Stack

#2951 → #2952 → #2953 → #2954 → #2955 → #2988 → #2993 → #2994 → this PR. Base: jev/8-target-readiness.

Why

The decisions path was written against one model (TypeSafe Jev). In the same week Cloudflare shipped Clef, Perplexity shipped Decider, and OpenAI announced a Decisions API: all answer typed questions with probabilities instead of text. Nothing above the HTTP client depends on which one answers, so the client becomes a provider seam.

What

• decisions/providers.ts — one codec per provider: how to address it, encode a request, read answers.
  • typesafe (default): unchanged wire, byte for byte (asserted by a test).
  • cloudflare: Clef / clef-flash on Workers AI (/accounts/{accountId}/ai/run/@cf/cloudflare/<model>), System One body, answers inside { result }.
  • perplexity: pplx-decider-v1-27b on /v1/decisions, System One body.
  • openai: Decisions API preview. No public schema exists; this follows the request/response recorded by a preview user (the same recording other libraries use): { input, questions: [{type: "predicate"|"choice", name, …}] } → { answers: [...] } with probability lists.
• decisions/client.ts (was typesafeClient.ts) — everything shared, so the pipeline sees one behaviour:
  • Answer validation. A choice must be one of the offered options, probabilities in range, the distribution consistent, and the choice its most likely option. Anything else is a typed error → the act falls back. This is new for TypeSafe too.
  • Ids and text. Providers with a restricted id alphabet or text-only fields get aliased keys/option ids (description keeps the original) and serialised JSON; answers always come back under the caller's ids.
  • Limits. Requests over a provider's question cap (64 / 128) are split over the same state and merged. A one-option choice is answered locally as certain (a softmax over one option is 1; Clef rejects fewer than two).
  • Timeout, Retry-After-aware retry, and the circuit breaker now keyed per provider + endpoint + key.
• Config: experimentalDecisions.provider and .accountId (schema + regenerated artefacts). Evals: EVAL_DECISIONS_PROVIDER.

Testing

decisionsProviders.test.ts (26)	One request through all four wire formats → identical normalised answers; aliasing round trip; splitting at each provider's cap; invalid answers rejected; auth / overload / garbage; TypeSafe wire unchanged; OpenAI request + recorded response; the 403 Decision API is not enabled gate named. Mutation-checked: breaking the Perplexity codec or the splitter fails the suite.
decisionsCrossProvider.test.ts (24)	Act (click, fill, hand-off), observe-several, extract pick-and-copy and a WebMCP tool call with instruction-span arguments, each through every provider.
decisionsProvidersLive.test.ts	Opt-in (DECISIONS_LIVE=1 + a key), skipped in CI.
Existing suites	Stubs that answered with ids that were never offered now go through a helper that keeps them within the options; one extract test had been passing on such an id.

Live status, stated plainly: TypeSafe passes the live conformance run (jev-1.13.0, 203 ms). Our OpenAI key gets 403 Decision API is not enabled for this user, reported as a skip. No Cloudflare or Perplexity credentials were available, so those two are verified against their documented formats only. Thresholds were tuned on Jev; other models' probabilities are not calibrated the same way and need their own eval pass.

---

Summary by cubic

Adds Cloudflare Clef, Perplexity Decider, and OpenAI's Decisions API preview as decision-model providers for the experimental decisions path, alongside the default TypeSafe Jev. Every provider's answers are now validated before they are acted on, and invalid answers fall back to the LLM pipeline.

Providers and shared client

• providers.ts defines one codec per provider: addressing, request encoding, and answer reading.
• The shared client handles validation, aliased ids and serialised JSON for restricted providers, splitting requests over a provider's question cap, and answering one-option choices locally as certain.
• Timeout, Retry-After retry, and the circuit breaker are now keyed per provider, endpoint, and key.

Config and live status

• experimentalDecisions gains provider and accountId options, with regenerated SDK artefacts and EVAL_DECISIONS_PROVIDER for evals.
• TypeSafe passes the live conformance run; the OpenAI key currently hits 403 Decision API is not enabled; Cloudflare and Perplexity are verified against their documented formats only.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: d523d42

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

This PR includes changesets to release 21 packages

Name	Type
@browserbasehq/stagehand-extension	Patch
@browserbasehq/stagehand-go	Patch
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-python	Patch
browse	Patch
@browserbasehq/stagehand-examples	Patch
@browserbasehq/stagehand-integrations	Patch
@browserbasehq/eve	Patch
@browserbasehq/stagehand-integrations-example-pi-facade	Patch
@browserbasehq/stagehand-integrations-claude-agent-sdk	Patch
@browserbasehq/stagehand-integrations-example-claude-code-facade	Patch
@browserbasehq/stagehand-integrations-codex-sdk	Patch
@browserbasehq/stagehand-integrations-example-codex-facade	Patch
@browserbasehq/stagehand-integrations-cursor-sdk	Patch
@browserbasehq/stagehand-integrations-deepagents-sdk	Patch
@browserbasehq/stagehand-integrations-eve-sdk	Patch
@browserbasehq/stagehand-integrations-fx-sdk	Patch
@browserbasehq/stagehand-integrations-mastra-sdk	Patch
@browserbasehq/stagehand-integrations-example-mastra-facade	Patch
@browserbasehq/stagehand-integrations-pi-sdk	Patch
@browserbasehq/stagehand-integrations-example-vercel-ai-facade	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