feat(observability): agent sessions read path — queries, API, scratchpad UI

[JeremyFunk]

Stack 4. Base: ai2/02-ingest-write-path's columns via ai2/03-vendors-rollup. The first read path over the AI classification columns: an Agent Sessions page fed by typed warehouse queries through one shared read interface.

What this does

One filter payload feeds two tabs over traces:

• Sessions — rows whose session key resolved at session granularity (AiSessionKeyState = 6), grouped by AiSessionKeyHash: time window, trace count, keyed-span/error counts, vendors, services.
• AI traces — every AI-classified row (AiVendor != '') at any key state, grouped by TraceId, with bestSessionKeyState explaining why a trace is or isn't in a session.

Classification is strictly per span and one trace routinely mixes vendors (a CrewAI orchestration span parenting OpenInference-instrumented OpenAI calls; an eve turn root over AI SDK spans), so vendors is an array on every row and vendor/service filters mean containment — they live in HAVING over the same aggregates the row reports, never in WHERE, which would silently drop the non-matching spans from the row's own counts. The facet queries arrayJoin one grouped subquery, so facet counts and list rows share a single grouping by construction.

Layering, bottom to top:

• packages/query-engine/src/ch/tables.ts — the traces DSL mirror gains the five Ai* columns.
• ch/queries/agent-sessions.ts — agentSessionsListQuery / agentTracesListQuery / agentSessionsFacetsQuery, with SQL-catalog baselines so the compiled SQL is reviewed text.
• observability/agent-sessions.ts — listAgentSessions / listAgentTraces / agentSessionsFacets over WarehouseExecutor: the read interface. The coming MCP tools and CLI call these functions, not the routes.
• packages/domain/src/http/agent-sessions.ts + apps/api/src/routes/internal/agent-sessions.http.ts — the internal HTTP contract and routes.
• apps/web/src/routes/agent-sessions/ — a deliberately throwaway single-file dashboard page (owner-declared scratchpad) to exercise the path end to end; the real frontend is a later stack. Its one behavioral fix: Reload bypasses the cache-grid window snap, so freshly ingested rows show up immediately instead of after the 5-minute snap window.

Session-key hashes are the only session identity here — the plaintext lives in SpanAttributes under vendor-specific keys, and resolving it for display is the vendor-integration layer's job on a later detail read. UInt64 hashes ride the JSON wire as strings.

Also ships bun run tinybird:truncate (dev convenience used while seeding this page): truncates the local Tinybird workspace's datasources, refusing non-localhost hosts without --force.

Testing

• Query tests pin the compiled SQL shapes (containment-in-HAVING, state/vendor predicates, facet grouping); the SQL-catalog e2e sweep runs them against a real ClickHouse (analyzer gate green, 162 tests across catalog + rollup).
• Verified live against tinybird-local with seeded classified spans: both tabs, containment filters, and per-tab facet counts correct in the browser.
• @maple/query-engine 1234, @maple/domain 514, apps/api 2082, repo typecheck 40/40.

🤖 Generated with Claude Code

---

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