v2.4.0 — Agent resources, analytics & multi-engine robustness

Backward-compatible feature release. All additions are opt-in; defaults are unchanged. 2198 tests passing.

Agent resources & relations

• AiResource — expose an Eloquent model as find_/create_/show_ tools from config or a fluent API, no per-entity tool classes. ->with() / ->detail() / ->detailOnly() add relation-aware record detail (an invoice with its line items). (#31, #37, #38)
• ResolvesAgentRelations — deterministic find-or-create of related records, so correctness doesn't depend on the planner remembering to call a create tool. (#32)

Structured analytics — aggregate_data

• Exact SUM/AVG/MIN/MAX/COUNT, ranked top/bottom records, and group_by breakdowns — replaces eyeballing a 10-row list (which produced 10×-wrong totals). (#40)
• Metric-aware cross-entity routing: "best selling product" / "revenue per product" aggregate the line items; "average product price" stays on the catalog; "which customer spent the most" groups invoices by customer. (#41)
• Relative-time + exact-value filters ("revenue this month", "how much has Apollo Labs spent"); count + group_by = distinct count; "list all" returns the full breakdown. (#42, #45)
• query optional — structured-only calls no longer leak "Missing required parameter" or fall back to the knowledge base. (#44)

Tool-context scaling

• ToolSelector strategies — skill_scoped, keyword, semantic — plus progressive disclosure (find_tools meta-tool), to keep the planner prompt small with large toolsets. Each fails open. (#33, #34, #35, #36)

Robustness

• Read-intent guard (opt-in) — a read query ("search for the invoice for X") can no longer trigger a write/create flow. (#39)
• Multi-engine failover skips engines with no API key (so a keyless fallback never surfaces " API key is required"); ai:doctor now reports per-engine credential health. (#43)

Upgrade notes

No breaking changes. New behavior is gated behind config (ai-agent.ai_native.*, ai-engine.data_query.models.* aggregatable/groupable, error_handling.fallback_engines). See docs/agent-resources.mdx and docs/orchestration-v2.mdx.