feat(query-engine): AI agent session queries + gen_ai integration layer

[JeremyFunk]

Read side for the AI agent session feature. The ingest gateway already stamps maple_ai.vendor.id / .vendor.version / .session.id at decode time (#517); this reads them back.

Built on main. Supersedes the stacked read path in #513, which predates the v2 write side — that chain can be closed if this lands.

Scope is the query and the integration layer only. The API surface (MCP, public API, dashboard) is a follow-up.

Queries — src/ai/ai-sessions.ts

maple_ai.session.id is sparse. A vendor stamps it on the spans that own the turn (ai.eve.turn, invoke_agent), never on the sibling chat, execute_tool or infrastructure spans in the same trace. So a session resolves at trace granularity: any span carrying the id pulls in every span of its trace, including the non-AI ones — the dashboard shows full agent context, not just the spans a framework happened to label.

aiSessionListQuery returns one row per session (vendor, trace/span/error counts, services, window, duration) with optional vendor and service filters. aiSessionSpansQuery returns every span of every trace in one session, with the full SpanAttributes / ResourceAttributes maps for the integration layer to map.

Both do that fan-out in two stages against two tables:

• detect — scans traces, where mapContains(SpanAttributes, 'maple_ai.session.id') rides the mapKeys(SpanAttributes) bloom index and stays cheap over a week. Yields the qualifying trace-id set and nothing else.
• fan out — reads trace_detail_spans, where TraceId is a sort-key prefix (OrgId, TraceId, SpanId).

The same fan-out on raw traces times out at 10s on a 7-day window in production — that table is sorted (OrgId, ServiceName, SpanName, Timestamp) and idx_trace_id is only a bloom skip index, which prunes far too little at real volume. Measured: a bare single-trace lookup alone exceeds the limit. No new table and no new index is involved; errorDetailTracesQuery already splits across these two tables for the same reason.

vendorId resolves via argMin over the earliest session-bearing span rather than max(). One trace legitimately carries several vendors — an eve agent calling through the Vercel AI SDK — and max() picked vercel_ai_sdk alphabetically when eve was the framework actually running the turn. The root-most session-bearing span is the one that names the framework.

The vendor and service filters both apply to the detection subquery. For service that means "the session-bearing spans came from this service" rather than "the trace touched this service" — a trace spans services by definition, so filtering the fan-out would silently drop spans and under-count spanCount.

Integration layer — ai-span-model.ts, ai-integrations.ts, ai-vendors.ts

A default gen_ai integration maps each span onto one standardised format covering all 62 GenAI semconv attributes. Every attribute in that convention is stability development, so there is no stable subset to draw a line at. Fields are declared once in AI_GENAI_FIELDS; the Effect schemas and the source-key table are both generated from it, so a new field cannot be added in one place and forgotten in another.

The default layer also reads the deprecated spellings — gen_ai.system, gen_ai.prompt/completion, gen_ai.usage.prompt_tokens/completion_tokens, the gen_ai.openai.* moves, singular finish_reason — and normalises their values where the rename changed them (vertex_ai → gcp.vertex_ai, tool_calls → tool_call). Source keys were taken from the GenAI semconv repo rather than the opentelemetry.io registry page, which is a stale snapshot: it still lists the deprecated set while missing 13 live attributes, including the whole gen_ai.memory.* family.

Per-vendor overrides are keyed on maple_ai.vendor.id and replace the default's source keys field by field. Three ship — vercel_ai_sdk (ai.*, read out of the installed SDK's own telemetry code), OpenInference (llm.* / input.value, covering both openinference-openai and unknown:openinference), and eve. Attribute keys that could not be verified against a source were dropped rather than guessed, along with two that would have silently mismapped: an SDK function id that is not an operation name, and a millisecond field where the convention is seconds. Adding a vendor is one table entry.

Attribute values arrive as strings from a ClickHouse Map(String, String), so decoding is tolerant by design: a value that will not parse yields undefined rather than throwing, and a span with no AI signal maps to isAiSpan: false with an empty payload.

Verification

• 264 tests in the package, tsc --noEmit clean, oxlint and oxfmt clean, @maple/api typechecks against it.
• Both queries run against the production warehouse over a 7-day window and return correctly.
• Real production rows fed through mapAiSpans produce the expected spans end to end, including the eve override, the legacy-dialect normalisations, and a non-AI infrastructure span mapping to isAiSpan: false.
• The __sql_baseline__ diff is additive only; no existing query's SQL changed.

Known limits

• The spans query caps at 2000 spans and truncates silently. One real trace is already 250 spans at up to ~17KB of attributes each. A hasMore signal or cursor belongs with the API surface.
• The time window bounds both query levels, so a session whose traces straddle the window edge returns partial spans.
• trace_detail_spans carries no ScopeName, so mapping keys off maple_ai.vendor.id alone. The gateway already performed scope-based detection at write time, but a span it failed to classify cannot be rescued in the read path.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}