Laravel Ai Bridge Laravel Package

Technical Evaluation

Architecture fit

• The package sits as a Laravel-side abstraction over an external ai-bridge service: HTTP client + service provider + configuration, exposing conversation routes and a connection-status endpoint. effort is implemented as a thin pass-through (ai_request.options.effort), which is the right shape — no new persistence, no new domain model, no schema change.
• Capability negotiation is done via the bridge's advertised effort_levels on the connection status endpoint rather than hardcoding a vocabulary. That is a sound pattern and gives us a forward-compatible seam for future thinking levels.
• v0.21.0 adds a package-level security boundary rather than a bridge-level one: CSRF enforcement on the state-changing browser routes introduced in 0.19 (POST /ai-bridge/connections/{id}/mcp, POST/DELETE .../upstreams/{server}/sign-in). This is the correct placement — the package owns the browser-facing surface, so it should own the token check — but it means the package is now a security control in our stack, not just an HTTP convenience wrapper.
• The CSRF guard deliberately ignores the app's allowSameSite() and CSRF except list and applies even to cookie-authenticated requests with no started session; only token-authenticated calls (bearer, Sanctum PAT) bypass. That is a defensible strict-by-default posture, but it establishes a second, independent CSRF policy alongside the host app's. Any team with an existing exemption on these paths now needs to know about it.
• tool_call_id being required on the mcp route ties a relayed call to a card that was actually shown — a data-integrity constraint on the relay, not a transport detail. The PHP API keeps it optional for trusted server code, which correctly preserves server-to-server ergonomics while tightening the browser path.
• Documentation has been restructured to Engram standard v1 (AGENTS.md, docs map, architecture page, decision records). For a TPM this is a meaningful maturity signal: ADRs give us an auditable rationale trail for the behaviour changes below, and AGENTS.md reduces agent-assisted contribution risk. v0.21 adds Decision 0009 — confirm it captures the CSRF threat model and the deliberate bypass of app-level exemptions.

Integration feasibility

• Requires ai-bridge >= 0.32.0 for effort to have any effect. This remains a hard cross-service dependency and a coordinated release, not an independent package bump.
• effort is scoped to Claude conversations only; BYOK and managed mode never transmit it. Any product surface exposing an effort control must branch on provider/mode or it will present a control that silently does nothing.
• Input contract is narrow: the conversation route returns 422 unless effort matches ^[a-z]{1,16}. Feasible, but the regex encodes an assumption (single lowercase token, no separators, no numerics). Verify current and planned level names fit before we build UI around it.
• v0.21.0 tightening: the mcp route now returns 422 tool_call_id_required. Any non-PHP consumer (front-end relay, JS proxy, webhook bridge) must be updated in lockstep. PHP callers of the client API are unaffected.
• CSRF surface is now configurable: ai-bridge.csrf.upstreams / AI_BRIDGE_CSRF_UPSTREAMS (defaults on for the 0.19 upstream routes) and ai-bridge.csrf.routes / AI_BRIDGE_CSRF_ROUTES (default off, applies the same check to the package's other state-changing browser routes, and becomes the default in the next major). The bundled <x-ai-bridge::chat /> sends the token itself; custom front-ends do not.
• Supported setups now explicitly require laravel/framework — confirm this is a real Composer constraint and not documentation-only.

Technical risk

• Behaviour change (still highest risk): a per-turn model now wins over the conversation's stored model. Previously the stored model was authoritative. Any existing caller that passes a model field incidentally — or that relied on the conversation's pinned model for cost/quality guarantees — will silently change routing and spend. This is not a deprecation; it is an immediate precedence flip with no opt-in described. Not addressed in v0.21.0.
• New breaking change (v0.21.0): tool_call_id required on the mcp HTTP route. A hard 422 for any relay that previously omitted it. Small blast radius if only the bundled component calls it; large if we proxy through our own front-end or workflow builder.
• New security-driven break: 419 csrf_token_mismatch on cookie/session-authenticated calls to the 0.19 routes. Custom clients — including single-page apps using cookie auth, and any cookie-authenticated-but-sessionless auth scheme — will fail until they send X-CSRF-TOKEN, _token, or X-XSRF-TOKEN. The guard explicitly overrides allowSameSite() and the app's CSRF except list, so existing exemptions do not protect these calls.
• Forward-looking break in the next major: ai-bridge.csrf.routes flips to default-on. Teams that do nothing today inherit a breaking change later; enabling it now converts a surprise into a controlled rollout.
• Opt-out is a foot-gun: AI_BRIDGE_CSRF_UPSTREAMS=false is only safe when the app itself protects these routes. If we disable it for a quick fix and forget, we reintroduce the cross-subdomain token-less attack the release exists to close.
• Silent no-op on older bridges. Sending effort to a pre-0.32 bridge does not error; it is ignored. Absent client-side feature detection, users will believe thinking level is applied when it is not. Still open.
• Empty effort_levels is ambiguous. It means "bridge too old," not "no levels available." Consumers must not treat empty as a valid empty capability set. Still open.
• Validation regex is a potential future-breaking constraint if effort labels ever become hyphens/numerics or exceed 16 chars.

Key questions

1. Is the per-turn model precedence change covered by an ADR, and is there an upgrade note or opt-in flag for consumers who depended on stored-model authority? (unchanged, still unanswered)
2. What is the canonical effort_levels vocabulary today, and is the ^[a-z]{1,16}$ constraint guaranteed stable across bridge releases? (unchanged)
3. Does the package declare a Composer constraint on ai-bridge (and now on laravel/framework), or are both requirements documentation-only?
4. Does the model-precedence change apply equally under BYOK and managed mode (where effort is suppressed)? (unchanged)
5. Is there an error/warning path when effort is supplied but unsupported by the connected bridge version? (unchanged)
6. New: Does Decision 0009 document the threat model and the deliberate bypass of allowSameSite() and the CSRF except list, and is there a timeline/issue for the next-major default for csrf.routes?
7. New: For cookie-authenticated-but-sessionless deployments, is any migration tooling or documented path offered, or is 419 the only signal?
8. New: Is tool_call_id validated against a stored card record (referential check) or only presence-checked? The release note implies the former; the implementation detail determines whether we need our own FK-style validation at the relay.
9. New: Does AI_BRIDGE_CSRF_UPSTREAMS=false disable both the upstream routes and the csrf.routes check, or only the former?

Integration Approach

Stack fit

• Standard Laravel integration surface: Composer dependency, publishable config, service provider, HTTP client to the bridge, and now middleware-level CSRF. Fits existing conventions; no framework-level impedance. The new guard is implemented with "Laravel's own CSRF middleware" semantics, which means our existing token plumbing (VerifyCsrfToken, Sanctum SPA cookie flow, axios defaults) should satisfy it in most cases.
• The package is effectively a two-component system (package + bridge). Treat its version matrix as a joint matrix in our dependency register rather than a single package pin. Add laravel/framework to the same matrix if the constraint is real.
• The package now owns a security control. Record it that way in the threat model and in any security review of the AI surface, rather than treating it as a library internal.

Migration path

1. Upgrade ai-bridge to >= 0.32.0 in all environments first, including staging and any preview/ephemeral environments. Confirm the connection status endpoint now returns a non-empty effort_levels. (unchanged)
2. Upgrade the package to v0.21.0.
3. Audit before enabling: grep all call sites and stored payloads for per-turn model fields. Enumerate which conversations currently rely on stored-model authority. This remains the gating item for the release, not the effort feature. (unchanged)
4. New — CSRF readiness: enumerate every browser-originated caller of /ai-bridge/connections/{id}/mcp and /upstreams/{server}/sign-in. Confirm each sends X-CSRF-TOKEN, _token, or X-XSRF-TOKEN. Confirm no caller depends on allowSameSite() or the app CSRF except list to reach those paths. Upgrade the bundled <x-ai-bridge::chat /> alongside the package so the token is sent automatically.
5. New — relay compatibility: add tool_call_id to every non-PHP mcp invocation. Treat this as a client release that must ship with (or before) the package upgrade.
6. New — opt-out hygiene: default AI_BRIDGE_CSRF_UPSTREAMS to on; only set false with a written justification referencing a specific app-level control, and add a config test asserting it stays unset.
7. New — pull forward the next-major break: enable ai-bridge.csrf.routes / AI_BRIDGE_CSRF_ROUTES in staging immediately and in production once step 4 is clean, so the next major is a no-op rather than a surprise.
8. Introduce an internal allowlist/config flag for effort selection and roll it out per provider, Claude-only. (unchanged)
9. Update API consumers and documentation for the 422 contracts on invalid effort and missing tool_call_id, plus 419 csrf_token_mismatch.

Compatibility

• Dual-version support window is unavoidable if any environment lags on ai-bridge < 0.32: in that window effort_levels is empty and effort is a silent no-op. Gate the UI on non-empty effort_levels, never on package version alone. (unchanged)
• v0.21.0 compatibility split: additive and non-breaking for PHP server-side callers (client API keeps tool_call_id optional); breaking for HTTP/browser callers on both the tool_call_id requirement and the CSRF check. Communicate it as breaking to integration teams even though the package may tag it minor.
• Security posture change: an app that previously relied on framework CSRF exemptions or allowSameSite() for these paths is now stricter post-upgrade. That is the point, but it must be announced as a behaviour change, not shipped silently.
• Known future break: csrf.routes default flips in the next major. Add it to our forward-compat tracker and, ideally, to our own changelog.
• The model-precedence change is a semantic break without a version-major signal. Flag it in our own changelog regardless of the package's semver. (unchanged)

Sequencing Bridge upgrade → package upgrade → model-precedence audit and remediation → CSRF client audit and token rollout → tool_call_id relay fix → enable csrf.routes early → effort feature detection in client → effort UI/API exposure → docs and support enablement → post-release verification of effective model logging and CSRF rejection rate. Do not invert the bridge/package steps ahead of the model-precedence audit; shipping the package before that audit risks unplanned model routing and cost. The CSRF steps (4–6) are independent of the bridge and can run in parallel, but they must complete before the package reaches production with any cookie-authenticated browser client in scope.

Operational Impact

Maintenance

• New standing obligation: keep the package and ai-bridge versions aligned. Any bridge release that changes effort_levels semantics or extends the level vocabulary is now a coordinated upgrade. (unchanged)
• New standing obligation: track the package's CSRF policy as a security control. Re-review on every upgrade whether new state-changing routes have been added and whether they are covered by csrf.upstreams or csrf.routes. The default flip in the next major is a scheduled item on our upgrade calendar.
• New config surface to govern: three-way decision per environment (csrf.upstreams, csrf.routes, and the two env vars). Recommend a single documented default posture — both on — and an explicit exception process for anything else.
• Documentation standard v1 reduces long-term maintenance drag (AGENTS.md, docs map, ADRs are versioned artifacts we can diff), but only if we actually track the ADR set as part of upgrade review. Add Decision 0009 to that set.

Support

• Expect a support tail from the model-precedence change: "the model changed without us changing anything." Mitigation requires per-turn effective-model logging in our own telemetry, since the package does not surface which model won. (unchanged)
• New support tail from CSRF: a wave of 419 csrf_token_mismatch from custom front-ends, particularly SPA and cookie-auth-without-session setups, and from anyone whose app had these routes in a CSRF except list. Pre-announce before rollout; do not let it surface as a mystery failure.
• New support tail from tool_call_id_required: 422s on relay paths that were fine yesterday. Fix is client-side; the diagnostic should name the field.
• 422s on invalid effort will surface as user-facing failures if the client does not validate against the same ^[a-z]{1,16}$ rule pre-flight. Mirror the validation client-side and in any admin tooling. (unchanged)
• Support runbook additions: (a) "effort selector visible but having no effect" → check bridge version and effort_levels emptiness (unchanged); (b) "419 on an AI route" → check token presence, then confirm AI_BRIDGE_CSRF_UPSTREAMS is not overridden, then check for a conflicting app-level exemption assumption; (c) "422 tool_call_id_required" → relay client version skew.

Scaling

• Negligible compute/latency impact: effort is a single scalar option on an existing request. The CSRF check is an in-process token comparison — no extra round trip. No additional network calls beyond the connection-status read, which should be cached with a short TTL.
• Cost scaling is the real axis. Higher thinking levels plus the new per-turn model precedence can compound spend. Add budget alerting keyed on effective model and effort level before broad rollout. (unchanged)
• New observability requirement: count 419s and 422s on the AI routes separately from other 4xx. A sudden spike is the earliest signal of a broken client after this upgrade.

Failure modes

• Silent model substitution — per-turn model overrides stored model; wrong model routed, cost/quality drift, no error raised. (unchanged, still open)
• Silent effort no-op — effort sent to bridge < 0.32 is discarded; users misled about thinking depth. (unchanged)
• Ambiguity collapse — empty effort_levels interpreted as "unsupported capability" rather than "old bridge," producing either a hidden feature or a broken one depending on interpretation. (unchanged)
• New — CSRF regression on legit clients: cookie-authenticated browser calls without a token now 419. Highest likelihood on custom SPAs and on any auth flow that uses cookies without a started session.
• New — exemption assumption drift: teams that previously relied on allowSameSite() or a CSRF except entry for these paths discover at runtime that the package's guard does not honour it. Especially likely where these routes were added post-exemption.
• New — opt-out left enabled: AI_BRIDGE_CSRF_UPSTREAMS=false set during an incident and never reverted, silently reopening the cross-subdomain vector the release closes.
• New — relay skew: a front-end or workflow tool still omitting tool_call_id after the package upgrade, producing 422s only on the browser path while server-side tests stay green.
• New — next-major cliff: csrf.routes default flip lands unmanaged because we deferred awareness of it.
• Validation drift — client and server regexes diverge; requests fail at the conversation route with 422 only in production. (unchanged)
• Partial rollout — UI exposing effort while some backend instances run an older bridge; inconsistent behaviour across nodes. (unchanged)
• Unpinned dependency — if the bridge or framework requirement is documentation-only, a Composer resolution may install an incompatible pair. (unchanged, now extends to laravel/framework)

Ramp-up

• Low for engineers: additive optional field on the effort path, standard docs, ADRs available. The security change is conceptually simple but requires reading the bypass semantics carefully.
• Moderate-to-high for front-end and integration teams: the CSRF and tool_call_id changes are breaking at the HTTP boundary even if the package semver says minor. Budget a written upgrade note, not just a release-note link.
• Moderate for support and product: requires understanding provider/mode scoping (Claude only; not BYOK, not managed), the model-precedence reversal, and now the CSRF token requirement and its interaction with existing app-level exemptions.
• Recommendation: adopt v0.21.0. Treat the per-turn model precedence change as the release's primary risk and gate rollout on the call-site audit; treat the CSRF hardening as the release's highest-urgency change — it is a genuine security fix, so schedule it early rather than deferring to a later window, but announce and verify every cookie-authenticated client first. Enforce tool_call_id at our relay in the same window. Enable csrf.routes proactively to absorb the next-major default. Treat effort as the lower-risk, opt-in feature it appears to be.