Laravel Ai Bridge Laravel Package

Product Decisions This Supports

• Exposing a quality/cost dial to users. Per-turn effort (Claude's thinking level) can back a user-facing control — "Fast / Balanced / Deep" — that trades latency and token spend against answer quality. This is a pricing-tier and UX decision, not just an engineering one.
• Capability-aware UI instead of hardcoded assumptions. The connection status reports the bridge's effort_levels. Render the selector only when the backend supports it, and degrade gracefully on older bridges (empty list before ai-bridge 0.32). Decide "show, hide, or grey out" from live capability data rather than a deploy-time guess.
• Per-turn model routing. Per-turn model wins over the conversation's stored model, unlocking mid-conversation escalation (cheap model for triage, stronger model for the hard follow-up), A/B testing of models within a single thread, and per-request fallback, without forking the conversation.
• Cost and margin modelling per segment. Effort is Claude-only and is never sent for BYOK or managed mode. Any pricing or quota work must model these segments separately; BYOK customers see no behaviour change and no new cost surface.
• Security posture as a product attribute. v0.21.0 closes a cross-subdomain hole on the bridge-mutating routes (MCP tool calls, upstream sign-in). That is a trust-and-sales decision: if we surface "your assistant can call tools on your servers," we need to be able to say those calls cannot be triggered by another subdomain riding a SameSite=Lax session cookie. Adopting the release is the cheapest way to make that claim true; hand-rolling it is now duplicated work.
• Auditability of tool calls. tool_call_id becoming required on the MCP route means every relayed request is tied to a card that was actually shown. That converts "the model could have called anything" into a per-render provenance trail — useful for support, incident review, and any enterprise security questionnaire.
• Breaking-change budget. 0.21.0 carries one breaking change on a browser-facing route. Whether that lands in this sprint or next is a release-planning decision, not an engineering one, and it should be sequenced against any customer sending MCP relay traffic.
• Build vs buy. Provider-specific thinking-level plumbing, option validation, capability negotiation, and now CSRF hardening on state-changing bridge routes are undifferentiated work. Adopting this keeps that surface in the package and out of our codebase, at the cost of a hard dependency floor (ai-bridge 0.32.0) and a pre-1.0 API.
• Client contract and error handling. The conversation route returns 422 unless effort matches ^[a-z]{1,16}; the MCP route now returns 422 tool_call_id_required; CSRF mismatch returns 419 csrf_token_mismatch. These are documented, testable client contracts — validate in the UI before the request, and map each code to a specific user message rather than a generic failure.
• Roadmap sequencing. A documented default flip is coming: ai-bridge.csrf.routes lands off in 0.21.0 and becomes the default in the next major. That is a scheduled migration we can plan for now rather than discover later. Docs standard v1 (AGENTS.md, docs map, architecture page, decision records) further lowers onboarding cost and makes the package a safer long-term bet.

When to Consider This Package

Consider it when:

• The product is Laravel-native and already talks to, or is willing to run, the ai-bridge service.
• Claude is the primary or only reasoning provider for the flows where reasoning depth matters; effort is Claude-only.
• You need both BYOK and managed modes in one codebase and want a single conversation abstraction over them.
• You want per-turn control (model, effort) without hand-rolling provider SDK calls, retries, and validation.
• You expose browser-reachable routes that act on a user's bridge (MCP tool calls, upstream sign-in). The CSRF enforcement added in 0.21.0 — which deliberately ignores allowSameSite() and the app's CSRF except list — is exactly the protection you would otherwise have to build and defend yourself.
• You want tool-call provenance: the required tool_call_id ties each relayed call to a rendered card, giving you a per-call audit trail for free.
• A pre-1.0 dependency is acceptable — v0.21.0 means the API can still move, and the last two releases have each carried a behaviour change.

Look elsewhere when:

• Non-Claude providers are the primary path. Effort buys you nothing there, and you would be paying the integration cost for an unused feature.
• BYOK or managed customers are the core segment. Effort never reaches them, so the effort feature is close to a no-op for that roadmap.
• You cannot move to ai-bridge 0.32.0. Effort silently does nothing on older bridges; you would ship a control that appears functional and is not.
• You cannot ship the CSRF change. If existing relay clients post to these routes without a token, they will start getting 419s. The escape hatch (ai-bridge.csrf.upstreams / AI_BRIDGE_CSRF_UPSTREAMS=false) is only defensible if the app already protects those routes itself — otherwise you are re-opening the subdomain hole.
• You rely on a conversation's stored model as the source of truth. The per-turn precedence rule can change behaviour in existing flows; any product logic built on "the conversation's model is authoritative" needs revisiting first.
• Your needs are single-shot completions. Conversation state, modes, and per-turn options are unnecessary surface area.

How to Pitch It (Stakeholders)

For executives: v0.21.0 is primarily a security release. It closes a real hole: another site on a same-site subdomain could previously ride a signed-in user's session cookie and make that user's bridge call tools on their connected servers. Those routes now require a CSRF token, and — separately — every relayed tool call must now carry a tool_call_id, so a call can always be traced back to something the user actually saw. There is one breaking change on that browser-facing MCP route, and it does not touch billing, pricing, or the BYOK/managed split. The previous release's cost-and-quality dial is unchanged and still requires ai-bridge 0.32.0. Worth flagging: a second CSRF flag (ai-bridge.csrf.routes) ships off but becomes the default in the next major, so there is a known migration on the horizon. Still a 0.x package — treat the API as settling.

For engineering: Two things to action. First, the bridge-mutating routes (POST /ai-bridge/connections/{id}/mcp, POST/DELETE .../upstreams/{server}/sign-in) now enforce CSRF via Laravel's own middleware whenever the request is session/cookie-authenticated — X-CSRF-TOKEN, _token, or X-XSRF-TOKEN. The check deliberately ignores allowSameSite() and the CSRF except list, and fires even without a started session. Only token-authenticated requests (bearer, Sanctum PATs) pass without a token. Mismatch is 419 csrf_token_mismatch. The bundled <x-ai-bridge::chat /> sends the token itself; any custom client we wrote does not, and will break. Only disable via AI_BRIDGE_CSRF_UPSTREAMS=false if the app independently protects those routes — and note the requirement on laravel/framework for the supported setup. Second, tool_call_id is now required on the MCP route (422 tool_call_id_required), so relay code must thread it through from the rendered card; the PHP API still treats it as optional for trusted server code, so this is a transport-layer change, not a breaking change to our server-side calls. Also carry forward from 0.20.0: read effort_levels from connection status, validate effort against ^[a-z]{1,16}, confirm bridge ≥ 0.32.0, and audit any assumption that a conversation's stored model wins. Track ai-bridge.csrf.routes for the next major. Add tests for the 419 and 422 paths alongside the existing precedence and capability-empty cases.

Ask: Confirm bridge 0.32.0 availability per environment and audit our relay clients for CSRF token handling before we take 0.21.0. Then decide whether the effort control ships as a user-facing setting or an internal routing lever before we commit UI.