feat: session list API (#23202)

<!--

If you have used AI to produce some or all of this PR, please ensure you have read our [AI Contribution guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING) before submitting.

-->

_Disclaimer:_ _initially_ _produced_ _by_ _Claude_ _Opus_ _4\.6,_ _heavily_ _modified_ _and_ _reviewed_ _by_ _me._

Closes https://github.com/coder/internal/issues/1360

Adds a new `/api/v2/aibridge/sessions` API which returns "sessions".

Sessions, as defined in the [RFC](https://www.notion.so/coderhq/AI-Bridge-Sessions-Threads-2ccd579be59280f28021d3baf7472fbe?source=copy_link), are a set of interceptions logically grouped by a session key issued by the client.  
The API design for this endpoint was done in [this doc](https://github.com/coder/internal/issues/1360).

If the client has not provided a session ID, we will revert to the thread root ID, and if that's not present we use the interception's own ID (i.e. a session of a single interception - which is effectively what we show currently in our `/api/v2/aibridge/interceptions` API).

The SQL query looks gnarly but it's relatively simple, and seems to perform well (~200ms) even when I import dogfood's `aibridge_*` tables into my workspace. If we need to improve performance on this later we can investigate materialized views, perhaps, but for now I don't think it's warranted.

---

_The PR looks large but it's got a lot of generated code; the actual changes aren't huge._

coderd/database/queries.sql.go

@@ -332,6 +332,77 @@ func (q *sqlQuerier) CountAIBridgeInterceptions(ctx context.Context, arg CountAI
 	return count, err
 }
 
+const countAIBridgeSessions = `-- name: CountAIBridgeSessions :one
+SELECT
+	COUNT(DISTINCT (aibridge_interceptions.session_id, aibridge_interceptions.initiator_id))
+FROM
+	aibridge_interceptions
+WHERE
+	-- Remove inflight interceptions (ones which lack an ended_at value).
+	aibridge_interceptions.ended_at IS NOT NULL
+	-- Filter by time frame
+	AND CASE
+		WHEN $1::timestamptz != '0001-01-01 00:00:00+00'::timestamptz THEN aibridge_interceptions.started_at >= $1::timestamptz
+		ELSE true
+	END
+	AND CASE
+		WHEN $2::timestamptz != '0001-01-01 00:00:00+00'::timestamptz THEN aibridge_interceptions.started_at <= $2::timestamptz
+		ELSE true
+	END
+	-- Filter initiator_id
+	AND CASE
+		WHEN $3::uuid != '00000000-0000-0000-0000-000000000000'::uuid THEN aibridge_interceptions.initiator_id = $3::uuid
+		ELSE true
+	END
+	-- Filter provider
+	AND CASE
+		WHEN $4::text != '' THEN aibridge_interceptions.provider = $4::text
+		ELSE true
+	END
+	-- Filter model
+	AND CASE
+		WHEN $5::text != '' THEN aibridge_interceptions.model = $5::text
+		ELSE true
+	END
+	-- Filter client
+	AND CASE
+		WHEN $6::text != '' THEN COALESCE(aibridge_interceptions.client, 'Unknown') = $6::text
+		ELSE true
+	END
+	-- Filter session_id
+	AND CASE
+		WHEN $7::text != '' THEN aibridge_interceptions.session_id = $7::text
+		ELSE true
+	END
+	-- Authorize Filter clause will be injected below in CountAuthorizedAIBridgeSessions
+	-- @authorize_filter
+`
+
+type CountAIBridgeSessionsParams struct {
+	StartedAfter  time.Time `db:"started_after" json:"started_after"`
+	StartedBefore time.Time `db:"started_before" json:"started_before"`
+	InitiatorID   uuid.UUID `db:"initiator_id" json:"initiator_id"`
+	Provider      string    `db:"provider" json:"provider"`
+	Model         string    `db:"model" json:"model"`
+	Client        string    `db:"client" json:"client"`
+	SessionID     string    `db:"session_id" json:"session_id"`
+}
+
+func (q *sqlQuerier) CountAIBridgeSessions(ctx context.Context, arg CountAIBridgeSessionsParams) (int64, error) {
+	row := q.db.QueryRowContext(ctx, countAIBridgeSessions,
+		arg.StartedAfter,
+		arg.StartedBefore,
+		arg.InitiatorID,
+		arg.Provider,
+		arg.Model,
+		arg.Client,
+		arg.SessionID,
+	)
+	var count int64
+	err := row.Scan(&count)
+	return count, err
+}
+
 const deleteOldAIBridgeRecords = `-- name: DeleteOldAIBridgeRecords :one
 WITH
   -- We don't have FK relationships between the dependent tables and aibridge_interceptions, so we can't rely on DELETE CASCADE.
@@ -384,7 +455,7 @@ func (q *sqlQuerier) DeleteOldAIBridgeRecords(ctx context.Context, beforeTime ti
 
 const getAIBridgeInterceptionByID = `-- name: GetAIBridgeInterceptionByID :one
 SELECT
-	id, initiator_id, provider, model, started_at, metadata, ended_at, api_key_id, client, thread_parent_id, thread_root_id, client_session_id
+	id, initiator_id, provider, model, started_at, metadata, ended_at, api_key_id, client, thread_parent_id, thread_root_id, client_session_id, session_id
 FROM
 	aibridge_interceptions
 WHERE
@@ -407,6 +478,7 @@ func (q *sqlQuerier) GetAIBridgeInterceptionByID(ctx context.Context, id uuid.UU
 		&i.ThreadParentID,
 		&i.ThreadRootID,
 		&i.ClientSessionID,
+		&i.SessionID,
 	)
 	return i, err
 }
@@ -441,7 +513,7 @@ func (q *sqlQuerier) GetAIBridgeInterceptionLineageByToolCallID(ctx context.Cont
 
 const getAIBridgeInterceptions = `-- name: GetAIBridgeInterceptions :many
 SELECT
-	id, initiator_id, provider, model, started_at, metadata, ended_at, api_key_id, client, thread_parent_id, thread_root_id, client_session_id
+	id, initiator_id, provider, model, started_at, metadata, ended_at, api_key_id, client, thread_parent_id, thread_root_id, client_session_id, session_id
 FROM
 	aibridge_interceptions
 `
@@ -468,6 +540,7 @@ func (q *sqlQuerier) GetAIBridgeInterceptions(ctx context.Context) ([]AIBridgeIn
 			&i.ThreadParentID,
 			&i.ThreadRootID,
 			&i.ClientSessionID,
+			&i.SessionID,
 		); err != nil {
 			return nil, err
 		}
@@ -618,7 +691,7 @@ INSERT INTO aibridge_interceptions (
 ) VALUES (
 	$1, $2, $3, $4, $5, COALESCE($6::jsonb, '{}'::jsonb), $7, $8, $9, $10::uuid, $11::uuid
 )
-RETURNING id, initiator_id, provider, model, started_at, metadata, ended_at, api_key_id, client, thread_parent_id, thread_root_id, client_session_id
+RETURNING id, initiator_id, provider, model, started_at, metadata, ended_at, api_key_id, client, thread_parent_id, thread_root_id, client_session_id, session_id
 `
 
 type InsertAIBridgeInterceptionParams struct {
@@ -663,6 +736,7 @@ func (q *sqlQuerier) InsertAIBridgeInterception(ctx context.Context, arg InsertA
 		&i.ThreadParentID,
 		&i.ThreadRootID,
 		&i.ClientSessionID,
+		&i.SessionID,
 	)
 	return i, err
 }
@@ -837,7 +911,7 @@ func (q *sqlQuerier) InsertAIBridgeUserPrompt(ctx context.Context, arg InsertAIB
 
 const listAIBridgeInterceptions = `-- name: ListAIBridgeInterceptions :many
 SELECT
-	aibridge_interceptions.id, aibridge_interceptions.initiator_id, aibridge_interceptions.provider, aibridge_interceptions.model, aibridge_interceptions.started_at, aibridge_interceptions.metadata, aibridge_interceptions.ended_at, aibridge_interceptions.api_key_id, aibridge_interceptions.client, aibridge_interceptions.thread_parent_id, aibridge_interceptions.thread_root_id, aibridge_interceptions.client_session_id,
+	aibridge_interceptions.id, aibridge_interceptions.initiator_id, aibridge_interceptions.provider, aibridge_interceptions.model, aibridge_interceptions.started_at, aibridge_interceptions.metadata, aibridge_interceptions.ended_at, aibridge_interceptions.api_key_id, aibridge_interceptions.client, aibridge_interceptions.thread_parent_id, aibridge_interceptions.thread_root_id, aibridge_interceptions.client_session_id, aibridge_interceptions.session_id,
 	visible_users.id, visible_users.username, visible_users.name, visible_users.avatar_url
 FROM
 	aibridge_interceptions
@@ -949,6 +1023,7 @@ func (q *sqlQuerier) ListAIBridgeInterceptions(ctx context.Context, arg ListAIBr
 			&i.AIBridgeInterception.ThreadParentID,
 			&i.AIBridgeInterception.ThreadRootID,
 			&i.AIBridgeInterception.ClientSessionID,
+			&i.AIBridgeInterception.SessionID,
 			&i.VisibleUser.ID,
 			&i.VisibleUser.Username,
 			&i.VisibleUser.Name,
@@ -1071,6 +1146,229 @@ func (q *sqlQuerier) ListAIBridgeModels(ctx context.Context, arg ListAIBridgeMod
 	return items, nil
 }
 
+const listAIBridgeSessions = `-- name: ListAIBridgeSessions :many
+WITH filtered_interceptions AS (
+	SELECT
+		aibridge_interceptions.id, aibridge_interceptions.initiator_id, aibridge_interceptions.provider, aibridge_interceptions.model, aibridge_interceptions.started_at, aibridge_interceptions.metadata, aibridge_interceptions.ended_at, aibridge_interceptions.api_key_id, aibridge_interceptions.client, aibridge_interceptions.thread_parent_id, aibridge_interceptions.thread_root_id, aibridge_interceptions.client_session_id, aibridge_interceptions.session_id
+	FROM
+		aibridge_interceptions
+	WHERE
+		-- Remove inflight interceptions (ones which lack an ended_at value).
+		aibridge_interceptions.ended_at IS NOT NULL
+		-- Filter by time frame
+		AND CASE
+			WHEN $4::timestamptz != '0001-01-01 00:00:00+00'::timestamptz THEN aibridge_interceptions.started_at >= $4::timestamptz
+			ELSE true
+		END
+		AND CASE
+			WHEN $5::timestamptz != '0001-01-01 00:00:00+00'::timestamptz THEN aibridge_interceptions.started_at <= $5::timestamptz
+			ELSE true
+		END
+		-- Filter initiator_id
+		AND CASE
+			WHEN $6::uuid != '00000000-0000-0000-0000-000000000000'::uuid THEN aibridge_interceptions.initiator_id = $6::uuid
+			ELSE true
+		END
+		-- Filter provider
+		AND CASE
+			WHEN $7::text != '' THEN aibridge_interceptions.provider = $7::text
+			ELSE true
+		END
+		-- Filter model
+		AND CASE
+			WHEN $8::text != '' THEN aibridge_interceptions.model = $8::text
+			ELSE true
+		END
+		-- Filter client
+		AND CASE
+			WHEN $9::text != '' THEN COALESCE(aibridge_interceptions.client, 'Unknown') = $9::text
+			ELSE true
+		END
+		-- Filter session_id
+		AND CASE
+			WHEN $10::text != '' THEN aibridge_interceptions.session_id = $10::text
+			ELSE true
+		END
+		-- Authorize Filter clause will be injected below in ListAuthorizedAIBridgeSessions
+		-- @authorize_filter
+),
+session_tokens AS (
+	-- Aggregate token usage across all interceptions in each session.
+	-- Group by (session_id, initiator_id) to avoid merging sessions from
+	-- different users who happen to share the same client_session_id.
+	SELECT
+		fi.session_id,
+		fi.initiator_id,
+		COALESCE(SUM(tu.input_tokens), 0)::bigint AS input_tokens,
+		COALESCE(SUM(tu.output_tokens), 0)::bigint AS output_tokens
+		-- TODO: add extra token types once https://github.com/coder/aibridge/issues/150 lands.
+	FROM
+		filtered_interceptions fi
+	LEFT JOIN
+		aibridge_token_usages tu ON fi.id = tu.interception_id
+	GROUP BY
+		fi.session_id, fi.initiator_id
+),
+session_root AS (
+	-- Build one summary row per session. Group by (session_id, initiator_id)
+	-- to avoid merging sessions from different users who happen to share the
+	-- same client_session_id. The ARRAY_AGG with ORDER BY picks values from
+	-- the chronologically first interception for fields that should represent
+	-- the session as a whole (client, metadata). Threads are counted as
+	-- distinct root interception IDs: an interception with a NULL
+	-- thread_root_id is itself a thread root.
+	SELECT
+		fi.session_id,
+		fi.initiator_id,
+		(ARRAY_AGG(fi.client ORDER BY fi.started_at, fi.id))[1] AS client,
+		(ARRAY_AGG(fi.metadata ORDER BY fi.started_at, fi.id))[1] AS metadata,
+		ARRAY_AGG(DISTINCT fi.provider ORDER BY fi.provider) AS providers,
+		ARRAY_AGG(DISTINCT fi.model ORDER BY fi.model) AS models,
+		MIN(fi.started_at) AS started_at,
+		MAX(fi.ended_at) AS ended_at,
+		COUNT(DISTINCT COALESCE(fi.thread_root_id, fi.id)) AS threads,
+		-- Collect IDs for lateral prompt lookup.
+		ARRAY_AGG(fi.id) AS interception_ids
+	FROM
+		filtered_interceptions fi
+	GROUP BY
+		fi.session_id, fi.initiator_id
+)
+SELECT
+	sr.session_id,
+	visible_users.id AS user_id,
+	visible_users.username AS user_username,
+	visible_users.name AS user_name,
+	visible_users.avatar_url AS user_avatar_url,
+	sr.providers::text[] AS providers,
+	sr.models::text[] AS models,
+	COALESCE(sr.client, '')::varchar(64) AS client,
+	sr.metadata::jsonb AS metadata,
+	sr.started_at::timestamptz AS started_at,
+	sr.ended_at::timestamptz AS ended_at,
+	sr.threads,
+	COALESCE(st.input_tokens, 0)::bigint AS input_tokens,
+	COALESCE(st.output_tokens, 0)::bigint AS output_tokens,
+	COALESCE(slp.prompt, '') AS last_prompt
+FROM
+	session_root sr
+JOIN
+	visible_users ON visible_users.id = sr.initiator_id
+LEFT JOIN
+	session_tokens st ON st.session_id = sr.session_id AND st.initiator_id = sr.initiator_id
+LEFT JOIN LATERAL (
+	-- Lateral join to efficiently fetch only the most recent user prompt
+	-- across all interceptions in the session, avoiding a full aggregation.
+	SELECT up.prompt
+	FROM aibridge_user_prompts up
+	WHERE up.interception_id = ANY(sr.interception_ids)
+	ORDER BY up.created_at DESC, up.id DESC
+	LIMIT 1
+) slp ON true
+WHERE
+	-- Cursor pagination: uses a composite (started_at, session_id) cursor
+	-- to support keyset pagination. The less-than comparison matches the
+	-- DESC sort order so that rows after the cursor come later in results.
+	CASE
+		WHEN $1::text != '' THEN (
+			(sr.started_at, sr.session_id) < (
+				(SELECT started_at FROM session_root WHERE session_id = $1),
+				$1::text
+			)
+		)
+		ELSE true
+	END
+ORDER BY
+	sr.started_at DESC,
+	sr.session_id DESC
+LIMIT COALESCE(NULLIF($3::integer, 0), 100)
+OFFSET $2
+`
+
+type ListAIBridgeSessionsParams struct {
+	AfterSessionID string    `db:"after_session_id" json:"after_session_id"`
+	Offset         int32     `db:"offset_" json:"offset_"`
+	Limit          int32     `db:"limit_" json:"limit_"`
+	StartedAfter   time.Time `db:"started_after" json:"started_after"`
+	StartedBefore  time.Time `db:"started_before" json:"started_before"`
+	InitiatorID    uuid.UUID `db:"initiator_id" json:"initiator_id"`
+	Provider       string    `db:"provider" json:"provider"`
+	Model          string    `db:"model" json:"model"`
+	Client         string    `db:"client" json:"client"`
+	SessionID      string    `db:"session_id" json:"session_id"`
+}
+
+type ListAIBridgeSessionsRow struct {
+	SessionID     string          `db:"session_id" json:"session_id"`
+	UserID        uuid.UUID       `db:"user_id" json:"user_id"`
+	UserUsername  string          `db:"user_username" json:"user_username"`
+	UserName      string          `db:"user_name" json:"user_name"`
+	UserAvatarUrl string          `db:"user_avatar_url" json:"user_avatar_url"`
+	Providers     []string        `db:"providers" json:"providers"`
+	Models        []string        `db:"models" json:"models"`
+	Client        string          `db:"client" json:"client"`
+	Metadata      json.RawMessage `db:"metadata" json:"metadata"`
+	StartedAt     time.Time       `db:"started_at" json:"started_at"`
+	EndedAt       time.Time       `db:"ended_at" json:"ended_at"`
+	Threads       int64           `db:"threads" json:"threads"`
+	InputTokens   int64           `db:"input_tokens" json:"input_tokens"`
+	OutputTokens  int64           `db:"output_tokens" json:"output_tokens"`
+	LastPrompt    string          `db:"last_prompt" json:"last_prompt"`
+}
+
+// Returns paginated sessions with aggregated metadata, token counts, and
+// the most recent user prompt. A "session" is a logical grouping of
+// interceptions that share the same session_id (set by the client).
+func (q *sqlQuerier) ListAIBridgeSessions(ctx context.Context, arg ListAIBridgeSessionsParams) ([]ListAIBridgeSessionsRow, error) {
+	rows, err := q.db.QueryContext(ctx, listAIBridgeSessions,
+		arg.AfterSessionID,
+		arg.Offset,
+		arg.Limit,
+		arg.StartedAfter,
+		arg.StartedBefore,
+		arg.InitiatorID,
+		arg.Provider,
+		arg.Model,
+		arg.Client,
+		arg.SessionID,
+	)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListAIBridgeSessionsRow
+	for rows.Next() {
+		var i ListAIBridgeSessionsRow
+		if err := rows.Scan(
+			&i.SessionID,
+			&i.UserID,
+			&i.UserUsername,
+			&i.UserName,
+			&i.UserAvatarUrl,
+			pq.Array(&i.Providers),
+			pq.Array(&i.Models),
+			&i.Client,
+			&i.Metadata,
+			&i.StartedAt,
+			&i.EndedAt,
+			&i.Threads,
+			&i.InputTokens,
+			&i.OutputTokens,
+			&i.LastPrompt,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
 const listAIBridgeTokenUsagesByInterceptionIDs = `-- name: ListAIBridgeTokenUsagesByInterceptionIDs :many
 SELECT
 	id, interception_id, provider_response_id, input_tokens, output_tokens, metadata, created_at
@@ -1209,7 +1507,7 @@ UPDATE aibridge_interceptions
 WHERE
 	id = $2::uuid
 	AND ended_at IS NULL
-RETURNING id, initiator_id, provider, model, started_at, metadata, ended_at, api_key_id, client, thread_parent_id, thread_root_id, client_session_id
+RETURNING id, initiator_id, provider, model, started_at, metadata, ended_at, api_key_id, client, thread_parent_id, thread_root_id, client_session_id, session_id
 `
 
 type UpdateAIBridgeInterceptionEndedParams struct {
@@ -1233,6 +1531,7 @@ func (q *sqlQuerier) UpdateAIBridgeInterceptionEnded(ctx context.Context, arg Up
 		&i.ThreadParentID,
 		&i.ThreadRootID,
 		&i.ClientSessionID,
+		&i.SessionID,
 	)
 	return i, err
 }