@xalia/agent 0.5.7 → 0.6.0

package/src/chat/data/database.ts

@@ -0,0 +1,982 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
+/* eslint-disable @typescript-eslint/no-unsafe-return */
+/* eslint-disable @typescript-eslint/no-unsafe-member-access */
+
+import {
+  TeamParticipant,
+  TeamRole,
+  SessionParticipantMap,
+  SessionData,
+  TeamInfo,
+  SessionMessage,
+  SessionCheckpoint,
+  UserMessageData,
+  SessionCreateData,
+} from "./dataModels";
+import { createClient, SupabaseClient } from "@supabase/supabase-js";
+import type * as supabase from "../../../../supabase/database.types";
+import {
+  AgentPreferences,
+  AgentProfile,
+  AgentTemplate,
+  ApiKey,
+  getLogger,
+  SavedAgentProfile,
+} from "@xalia/xmcp/sdk";
+
+const logger = getLogger();
+
+export const SESSION_ALLOWED_PARTICIPANTS = ["owner", "participant"];
+
+export const SUPABASE_LOCAL_URL = "http://127.0.0.1:54321";
+export const SUPABASE_LOCAL_KEY =
+  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiw" +
+  "icm9sZSI6InNlcnZpY2Vfcm9sZSIsImV4cCI6MTk4MzgxMjk5Nn0.EGIM96RAZx35lJz" +
+  "dJsyH-qQwv8Hdp7fsn3W0YpN81IU";
+
+export function createSessionParticipantMap(
+  participants: TeamParticipant[]
+): SessionParticipantMap {
+  const pmap: SessionParticipantMap = new Map();
+  participants.forEach((p) => {
+    pmap.set(p.user_uuid, p);
+  });
+
+  return pmap;
+}
+
+/**
+ * 'name' -> 'name'
+ * 'space/name' -> ['space', 'name']
+ */
+export function resolveCompoundName(name: string): string | [string, string] {
+  const components = name.split("/");
+  if (components.length === 1) {
+    return name;
+  }
+  if (components.length !== 2) {
+    throw new Error("invalid compound name");
+  }
+  return components as [string, string];
+}
+
+export type UserData = {
+  uuid: supabase.Tables<"api_keys">["user_uuid"];
+  nickname: supabase.Tables<"users">["nickname"];
+  email: supabase.Tables<"users">["email"];
+  timezone: supabase.Tables<"users">["timezone"];
+};
+
+export class DbClientBase {
+  constructor(protected client: SupabaseClient) {}
+}
+
+export class Database {
+  private client: SupabaseClient;
+
+  constructor(supabaseUrl: string, supabaseKey: string) {
+    this.client = createClient(supabaseUrl, supabaseKey);
+  }
+
+  /**
+   * Get the underlying Supabase client for testing purposes only.
+   * DO NOT use in production code - use Database methods instead.
+   */
+  getClientForTesting(): SupabaseClient {
+    return this.client;
+  }
+
+  async getUserDataFromApiKey(apiKey: string): Promise<UserData | undefined> {
+    const { data, error } = await this.client
+      .from("api_keys")
+      .select("user_uuid, users ( nickname, timezone, email )")
+      .eq("api_key", apiKey)
+      .maybeSingle<{
+        user_uuid: supabase.Tables<"api_keys">["user_uuid"];
+        users: {
+          nickname: supabase.Tables<"users">["nickname"];
+          timezone: supabase.Tables<"users">["timezone"];
+          email: supabase.Tables<"users">["email"];
+        };
+      }>();
+
+    logger.debug(
+      `[getUserDataFromApiKey]: got ${JSON.stringify({ data, error })}`
+    );
+
+    if (error) {
+      throw error;
+    }
+
+    if (data === null) {
+      return undefined;
+    }
+
+    return {
+      uuid: data.user_uuid,
+      email: data.users.email,
+      nickname: data.users.nickname || `user ${data.user_uuid}`,
+      timezone: data.users.timezone || "UTC",
+    };
+  }
+
+  async getUserFromUuid(user_uuid: string): Promise<UserData | undefined> {
+    const { data, error } = await this.client
+      .from("users")
+      .select("*")
+      .eq("uuid", user_uuid)
+      .maybeSingle();
+    if (error) {
+      throw error;
+    }
+
+    return data;
+  }
+
+  async getUserByEmail(email: string): Promise<UserData | undefined> {
+    const { data, error } = await this.client
+      .from("users")
+      .select("*")
+      .eq("email", email)
+      .maybeSingle();
+    if (error) {
+      throw error;
+    }
+
+    return data;
+  }
+
+  async createUser(
+    user_uuid: string,
+    email: string,
+    nickname: string,
+    timezone?: string
+  ): Promise<void> {
+    const payload: supabase.TablesInsert<"users"> = {
+      uuid: user_uuid,
+      email,
+      nickname,
+      timezone: timezone || "UTC",
+    };
+
+    const { error } = await this.client.from("users").insert(payload);
+    if (error) {
+      throw error;
+    }
+  }
+
+  async addApiKey(
+    user_uuid: string,
+    api_key: string,
+    name: string,
+    scopes: string[],
+    is_default: boolean = false
+  ): Promise<ApiKey> {
+    const payload: supabase.TablesInsert<"api_keys"> = {
+      user_uuid,
+      api_key,
+      name,
+      scopes,
+      is_default,
+    };
+    const { data, error } = await this.client
+      .from("api_keys")
+      .insert(payload)
+      .select("*")
+      .maybeSingle();
+    if (error) {
+      throw error;
+    }
+
+    return data;
+  }
+
+  /**
+   * Get user's default API key from user UUID
+   * NOTE: this should only be used for accessing
+   * the session owner's API key.
+   * */
+  async getUserApiKey(user_uuid: string): Promise<string | undefined> {
+    const { data, error } = await this.client
+      .from("api_keys")
+      .select("api_key")
+      .eq("user_uuid", user_uuid)
+      .eq("is_default", true)
+      .maybeSingle();
+
+    if (error) {
+      throw error;
+    }
+    return data?.api_key;
+  }
+
+  async getSavedAgentProfileById(
+    agentProfileId: string
+  ): Promise<SavedAgentProfile | undefined> {
+    const { data, error } = await this.client
+      .from("agent_profiles")
+      .select("*")
+      .eq("uuid", agentProfileId)
+      .maybeSingle<supabase.Tables<"agent_profiles">>();
+    if (error) {
+      throw error;
+    }
+
+    return data
+      ? SavedAgentProfile.fromJSONObj(data as Record<string, unknown>)
+      : undefined;
+  }
+
+  async getSavedAgentProfileByName(
+    user_uuid: string,
+    agentProfileName: string
+  ): Promise<SavedAgentProfile | undefined> {
+    const { data, error } = await this.client
+      .from("agent_profiles")
+      .select("*")
+      .eq("user_uuid", user_uuid)
+      .eq("profile_name", agentProfileName)
+      .maybeSingle<supabase.Tables<"agent_profiles">>();
+    if (error) {
+      throw error;
+    }
+
+    return data
+      ? SavedAgentProfile.fromJSONObj(data as Record<string, unknown>)
+      : undefined;
+  }
+
+  async getAgentProfileById(
+    agentProfileId: string
+  ): Promise<AgentProfile | undefined> {
+    const { data, error } = await this.client
+      .from("agent_profiles")
+      .select("profile")
+      .eq("uuid", agentProfileId)
+      .maybeSingle<{
+        profile: supabase.Tables<"agent_profiles">["profile"];
+      }>();
+    if (error) {
+      throw error;
+    }
+    return data
+      ? AgentProfile.fromJSONObj(data.profile as Record<string, unknown>)
+      : undefined;
+  }
+
+  async createAgentProfile(
+    user_uuid: string | undefined,
+    team_uuid: string | undefined,
+    profileName: string,
+    profile: AgentProfile
+  ): Promise<SavedAgentProfile | undefined> {
+    const payload: supabase.TablesInsert<"agent_profiles"> = {
+      profile: profile as unknown as supabase.Json,
+      user_uuid,
+      team_uuid,
+      profile_name: profileName,
+    };
+    const { data, error } = await this.client
+      .from("agent_profiles")
+      .upsert(payload)
+      .select("*");
+    if (error) {
+      throw error;
+    }
+
+    return data[0]
+      ? SavedAgentProfile.fromJSONObj(data[0] as Record<string, unknown>)
+      : undefined;
+  }
+
+  async updateAgentProfile(uuid: string, profile: AgentProfile): Promise<void> {
+    const payload: supabase.TablesUpdate<"agent_profiles"> = {
+      profile: profile as unknown as supabase.Json,
+    };
+    const { error } = await this.client
+      .from("agent_profiles")
+      .update(payload)
+      .eq("uuid", uuid);
+    if (error) {
+      throw error;
+    }
+  }
+
+  async getAgentProfilePreferences(
+    agentProfileId: string
+  ): Promise<AgentPreferences | undefined> {
+    const { data, error } = await this.client
+      .from("agent_profiles")
+      .select("preferences")
+      .eq("uuid", agentProfileId)
+      .maybeSingle<{
+        preferences: supabase.Tables<"agent_profiles">["preferences"];
+      }>();
+    if (error) {
+      throw error;
+    }
+
+    return data ? (data.preferences as AgentPreferences) : undefined;
+  }
+
+  async updateAgentProfilePreferences(
+    agentProfileId: string,
+    preferences: AgentPreferences
+  ): Promise<void> {
+    const payload: supabase.TablesUpdate<"agent_profiles"> = { preferences };
+    const { error } = await this.client
+      .from("agent_profiles")
+      .update(payload)
+      .eq("uuid", agentProfileId);
+    if (error) {
+      throw error;
+    }
+  }
+
+  async clearAgentProfiles(): Promise<void> {
+    await this.client.from("agent_profiles").delete().neq("uuid", "");
+  }
+
+  //
+  // sessions
+  //
+
+  static sessionNewUUID(): string {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+
+    return Array.from(bytes)
+      .map((b) => b.toString(16).padStart(2, "0"))
+      .join("")
+      .padStart(32, "0"); // in case of leading zeros
+  }
+
+  async sessionsGet(): Promise<supabase.Tables<"sessions">[]> {
+    const { data, error } = await this.client.from("sessions").select("*");
+
+    if (error) {
+      throw error;
+    }
+    return data;
+  }
+
+  async sessionGetById(session_uuid: string): Promise<SessionData | undefined> {
+    const { data, error } = await this.client
+      .from("sessions")
+      .select("*")
+      .eq("uuid", session_uuid)
+      .maybeSingle();
+
+    if (error) {
+      throw error;
+    }
+
+    if (!data) {
+      return undefined;
+    }
+
+    return {
+      ...data,
+      workspace: data.workspace || undefined,
+      owner_uuid: data.user_uuid,
+      session_uuid: data.uuid,
+      updated_at: data.updated_at || new Date().toISOString(),
+    };
+  }
+
+  async sessionGetByName(
+    user_uuid: string,
+    session_name: string
+  ): Promise<SessionData | undefined> {
+    const { data, error } = await this.client
+      .from("sessions")
+      .select("*")
+      .eq("user_uuid", user_uuid)
+      .eq("title", session_name)
+      .maybeSingle();
+
+    if (error) {
+      logger.error(`[getSessionByName] error: ${JSON.stringify(error)}`);
+      throw error;
+    }
+    return {
+      ...data,
+      workspace: data.workspace || undefined,
+      owner_uuid: data.user_uuid,
+      session_uuid: data.uuid,
+      updated_at: data.updated_at || new Date().toISOString(),
+    };
+  }
+
+  async sessionCreate(session_data: SessionCreateData): Promise<void> {
+    const payload: supabase.TablesInsert<"sessions"> = {
+      uuid: session_data.session_uuid,
+      title: session_data.title,
+      agent_profile_uuid: session_data.agent_profile_uuid,
+      user_uuid: session_data.user_uuid,
+      team_uuid: session_data.team_uuid,
+      workspace: session_data.workspace,
+    };
+    const { error } = await this.client.from("sessions").insert(payload);
+    if (error) {
+      throw error;
+    }
+  }
+
+  async sessionUpdateTitle(session_uuid: string, title: string): Promise<void> {
+    const payload: supabase.TablesUpdate<"sessions"> = {
+      title,
+    };
+    const { error } = await this.client
+      .from("sessions")
+      .update(payload)
+      .eq("uuid", session_uuid);
+    if (error) {
+      throw error;
+    }
+  }
+
+  async sessionUpdateWorkspace(
+    session_uuid: string,
+    workspace: UserMessageData | undefined
+  ): Promise<void> {
+    const payload: supabase.TablesUpdate<"sessions"> = {
+      workspace: workspace || null,
+    };
+    const { error } = await this.client
+      .from("sessions")
+      .update(payload)
+      .eq("uuid", session_uuid);
+    if (error) {
+      throw error;
+    }
+  }
+
+  async sessionDeleteById(session_uuid: string): Promise<void> {
+    await this.client.from("sessions").delete().eq("uuid", session_uuid);
+  }
+
+  async clearSessions(): Promise<void> {
+    await this.client.from("sessions").delete().neq("uuid", "");
+  }
+
+  /**
+   * Get all user sessions (not including team sessions) for a user.
+   * @param user_uuid
+   * @returns SessionData[]
+   */
+  async getUserSessions(user_uuid: string): Promise<SessionData[]> {
+    const { data: userSessions, error: userSessionsError } = await this.client
+      .from("sessions")
+      .select(
+        "uuid, title, agent_profile_uuid, workspace, updated_at, user_uuid"
+      )
+      .eq("user_uuid", user_uuid)
+      .is("team_uuid", null);
+
+    if (userSessionsError) {
+      throw userSessionsError;
+    }
+
+    return userSessions.map((s) => ({
+      session_uuid: s.uuid,
+      title: s.title,
+      team_uuid: undefined,
+      agent_profile_uuid: s.agent_profile_uuid,
+      workspace: s.workspace || undefined,
+      updated_at: s.updated_at,
+      user_uuid: s.user_uuid,
+    }));
+  }
+
+  async sessionGetParticipants(
+    session_uuid: string
+  ): Promise<TeamParticipant[]> {
+    // check if session is a team session
+    const { data, error } = await this.client
+      .from("sessions")
+      .select("team_uuid, user_uuid")
+      .eq("uuid", session_uuid)
+      .maybeSingle();
+
+    if (error || !data) {
+      throw error || new Error("Session not found");
+    }
+
+    if (data.team_uuid) {
+      return this.teamGetMembers(data.team_uuid as string);
+    } else {
+      const userData = await this.getUserFromUuid(data.user_uuid as string);
+      if (!userData) {
+        throw new Error("Cannot find user data");
+      }
+      return [
+        {
+          user_uuid: data.user_uuid,
+          nickname: userData.nickname || "",
+          email: userData.email,
+          role: "owner",
+        },
+      ];
+    }
+  }
+
+  async sessionGetTeamUuid(session_uuid: string): Promise<string | undefined> {
+    const data = await this.sessionGetById(session_uuid);
+    if (data) {
+      return data.team_uuid;
+    }
+    return undefined;
+  }
+
+  //
+  // session_messages
+  //
+
+  async sessionMessagesClearConversation(session_uuid: string): Promise<void> {
+    const { error } = await this.client
+      .from("session_messages")
+      .delete()
+      .eq("session_uuid", session_uuid);
+    if (error) {
+      throw error;
+    }
+  }
+
+  async sessionMessagesGetConversation(
+    session_uuid: string,
+    numEntries: number,
+    beforeIndex?: number
+  ): Promise<SessionMessage[]> {
+    // Query all message for the given session, ordered high-to-low by
+    // message_idx, limited to `numEntries`.  If `beforeIndex` is given, it
+    // means we get messages with `message_idx < beforeIndex`
+
+    let query = this.client
+      .from("session_messages")
+      .select("message_idx,sender_uuid,is_for_llm,content")
+      .eq("session_uuid", session_uuid);
+    if (beforeIndex) {
+      query = query.lt("message_idx", beforeIndex);
+    }
+    query = query.order("message_idx", { ascending: false }).limit(numEntries);
+
+    const { data, error } = await query;
+    if (error) {
+      throw error;
+    }
+
+    // To get the newest N messages, we've orded by index largest to smallest
+    // (newest first), but caller wants the message first to last, hence
+    // reverse the array.
+
+    return data
+      .map(({ sender_uuid, ...rest }) => {
+        return sender_uuid
+          ? {
+              sender_uuid,
+              ...rest,
+            }
+          : { ...rest };
+      })
+      .reverse();
+  }
+
+  async sessionMessagesAppend(
+    session_uuid: string,
+    messages: SessionMessage[]
+  ): Promise<void> {
+    const payload = messages.map((m) => {
+      return { ...m, session_uuid };
+    });
+    const { error } = await this.client
+      .from("session_messages")
+      .insert(payload);
+    if (error) {
+      throw error;
+    }
+  }
+
+  //
+  // session_checkpoints
+  //
+
+  async sessionCheckpointsClear(): Promise<void> {
+    const { error } = await this.client
+      .from("session_checkpoints")
+      .delete()
+      .neq("session_uuid", "");
+    if (error) {
+      throw error;
+    }
+  }
+
+  async sessionCheckpointGet(
+    session_uuid: string
+  ): Promise<SessionCheckpoint | undefined> {
+    const { error, data } = await this.client
+      .from("session_checkpoints")
+      .select("message_idx,summary")
+      .eq("session_uuid", session_uuid)
+      .maybeSingle();
+
+    if (error) {
+      throw error;
+    }
+
+    if (!data) {
+      return undefined;
+    }
+
+    return {
+      message_idx: data.message_idx,
+      summary: data.summary,
+    };
+  }
+
+  async sessionCheckpointSet(
+    session_uuid: string,
+    checkpoint: SessionCheckpoint
+  ): Promise<void> {
+    const payload: supabase.TablesUpdate<"session_checkpoints"> = {
+      session_uuid,
+      message_idx: checkpoint.message_idx,
+      summary: checkpoint.summary,
+    };
+
+    const { error } = await this.client
+      .from("session_checkpoints")
+      .upsert([payload], { onConflict: "session_uuid" });
+    if (error) {
+      throw error;
+    }
+  }
+
+  //
+  // agent_profiles
+  //
+
+  /**
+   * Get all agents belonging to a user.
+   * @param userUuid - UUID of the user
+   * @returns Array of agent profiles
+   */
+  async agentProfilesGetByUser(userUuid: string): Promise<SavedAgentProfile[]> {
+    const { data, error } = await this.client
+      .from("agent_profiles")
+      .select("*")
+      .eq("user_uuid", userUuid);
+
+    if (error) {
+      throw error;
+    }
+
+    return data.map((agent) =>
+      SavedAgentProfile.fromJSONObj(agent as Record<string, unknown>)
+    );
+  }
+
+  /**
+   * Get all agents belonging to a team.
+   * @param teamUuid - UUID of the team
+   * @returns Array of agent profiles
+   */
+  async AgentProfilesGetByTeam(teamUuid: string): Promise<SavedAgentProfile[]> {
+    const { data, error } = await this.client
+      .from("agent_profiles")
+      .select("*")
+      .eq("team_uuid", teamUuid);
+
+    if (error) {
+      throw error;
+    }
+
+    return data.map((agent) =>
+      SavedAgentProfile.fromJSONObj(agent as Record<string, unknown>)
+    );
+  }
+
+  async agentTemplateGetByName(
+    templateName: string
+  ): Promise<AgentTemplate | undefined> {
+    const { data, error } = await this.client
+      .from("agent_templates")
+      .select("*")
+      .eq("name", templateName)
+      .maybeSingle();
+    if (error) {
+      throw error;
+    }
+    return data
+      ? AgentTemplate.fromJSONObj(data as Record<string, unknown>)
+      : undefined;
+  }
+  //
+  // teams
+  //
+
+  async createTeam(teamName: string, owner_uuid: string): Promise<string> {
+    const { data, error } = await this.client.rpc("create_team_with_owner", {
+      p_owner_uuid: owner_uuid,
+      p_name: teamName,
+    });
+    if (error) {
+      throw error;
+    }
+    // The SQL function returns a TEXT (team UUID)
+    return data as string;
+  }
+
+  /**
+   * Creates a team with initial participants.
+   * The owner is automatically added as a team member with 'owner' role.
+   * @param teamName - Name of the team to create
+   * @param ownerUuid - UUID of the team owner
+   * @param initialParticipants - Array of user UUIDs to add as initial members
+   * @returns The UUID of the created team
+   */
+  async createTeamWithParticipants(
+    teamName: string,
+    ownerUuid: string,
+    initialParticipants: string[]
+  ): Promise<string> {
+    // Create the team first
+    const teamUuid = await this.createTeam(teamName, ownerUuid);
+
+    // If there are initial participants, add them to the team
+    if (initialParticipants.length > 0) {
+      // Filter out the owner if they're in the initial participants list
+      const participantsToAdd = initialParticipants.filter(
+        (uuid) => uuid !== ownerUuid
+      );
+
+      if (participantsToAdd.length > 0) {
+        // Add all participants to the
+        const teamMemberInserts = participantsToAdd.map((userUuid) => ({
+          team_uuid: teamUuid,
+          user_uuid: userUuid,
+          role: "participant" as const,
+        }));
+
+        const { error: membersError } = await this.client
+          .from("team_members")
+          .insert(teamMemberInserts);
+
+        if (membersError) {
+          // If adding members fails, we should clean up the team
+          logger.error(
+            `Failed to add members to team ${teamUuid}: ${membersError.message}`
+          );
+          // Optionally delete the team if member addition fails
+          await this.deleteTeam(teamUuid);
+          throw membersError;
+        }
+      }
+    }
+
+    logger.info(
+      `Created team ${teamUuid}: ${String(initialParticipants.length)} members`
+    );
+
+    return teamUuid;
+  }
+
+  /**
+   * Deletes a team and all associated data.
+   * This will also remove all team members and any team sessions.
+   * @param teamUuid - UUID of the team to delete
+   */
+  async deleteTeam(teamUuid: string): Promise<void> {
+    try {
+      // Delete the team - this should cascade to team_members and team_sessions
+      // due to foreign key constraints with ON DELETE CASCADE
+      const { error } = await this.client
+        .from("teams")
+        .delete()
+        .eq("uuid", teamUuid);
+
+      if (error) {
+        throw error;
+      }
+
+      logger.info(`Deleted team ${teamUuid}`);
+    } catch (error) {
+      logger.error(`Failed to delete team ${teamUuid}:`, error);
+      throw new Error(`Failed to delete team: ${String(error)}`);
+    }
+  }
+
+  async getTeamInfosByUser(user_uuid: string): Promise<TeamInfo[]> {
+    // Get all teams the user is a member of (including as owner)
+    const { data: teamMemberships, error: teamError } = await this.client
+      .from("team_members")
+      .select(
+        `
+        team_uuid,
+        role,
+        teams!inner (
+          uuid,
+          name,
+          owner_uuid
+        )
+      `
+      )
+      .eq("user_uuid", user_uuid);
+
+    if (teamError) {
+      throw teamError;
+    }
+
+    if (teamMemberships.length === 0) {
+      return [];
+    }
+
+    // Process all team memberships in parallel
+    const teamSessionPromises = teamMemberships.map(async (membership) => {
+      const teamUuid: string = membership.team_uuid;
+      const teamData = membership.teams as unknown as {
+        uuid: string;
+        name: string;
+        owner_uuid: string;
+      };
+
+      // Use the role from team_members, sanity check against teams.owner_uuid
+      const memberRole = membership.role as TeamRole;
+      const isActualOwner = teamData.owner_uuid === user_uuid;
+
+      // Sanity check: if roles are inconsistent, throw an error
+      if (
+        (memberRole === "owner" && !isActualOwner) ||
+        (memberRole !== "owner" && isActualOwner)
+      ) {
+        throw new Error(
+          `Data inconsistency: user ${user_uuid} has role '${memberRole}' ` +
+            `in team ${teamUuid}, but owner is ${teamData.owner_uuid}`
+        );
+      }
+
+      // Fetch team members and sessions in parallel using helper methods
+      const [participants, sessions, agents] = await Promise.all([
+        this.teamGetMembers(teamUuid),
+        this.teamGetSessions(teamUuid),
+        this.AgentProfilesGetByTeam(teamUuid),
+      ]);
+
+      return {
+        team_uuid: teamUuid,
+        team_name: teamData.name,
+        owner_uuid: teamData.owner_uuid,
+        participants,
+        sessions,
+        agents,
+      };
+    });
+
+    return await Promise.all(teamSessionPromises);
+  }
+
+  /**
+   * Get all members of a team.
+   * @param teamUuid - UUID of the team
+   * @returns Array of team members with their roles
+   */
+  async teamGetMembers(teamUuid: string): Promise<TeamParticipant[]> {
+    const { data, error } = await this.client
+      .from("team_members")
+      .select("user_uuid, role")
+      .eq("team_uuid", teamUuid);
+
+    if (error) {
+      throw error;
+    }
+
+    // get users' data in parallel
+    const usersData = await Promise.all(
+      data.map((member) => this.getUserFromUuid(member.user_uuid as string))
+    );
+
+    usersData.forEach((user) => {
+      if (!user) {
+        throw new Error("Cannot find user data");
+      }
+    });
+
+    const result = data.map((member, index) => ({
+      user_uuid: member.user_uuid,
+      nickname: usersData[index]?.nickname || "",
+      email: usersData[index]?.email || "",
+      role: member.role as TeamRole,
+    }));
+
+    return result;
+  }
+
+  /**
+   * Add a member to a team as a participant.
+   * @param teamUuid - UUID of the team
+   * @param userUuid - UUID of the user to add
+   */
+  async teamAddMember(teamUuid: string, userUuid: string): Promise<void> {
+    const { error } = await this.client.from("team_members").insert({
+      team_uuid: teamUuid,
+      user_uuid: userUuid,
+      role: "participant",
+    });
+
+    if (error) {
+      throw error;
+    }
+  }
+
+  /**
+   * Remove a member from a team.
+   * @param teamUuid - UUID of the team
+   * @param userUuid - UUID of the user to remove
+   */
+  async teamRemoveMember(teamUuid: string, userUuid: string): Promise<void> {
+    const { error } = await this.client
+      .from("team_members")
+      .delete()
+      .eq("team_uuid", teamUuid)
+      .eq("user_uuid", userUuid)
+      .eq("role", "participant");
+
+    if (error) {
+      throw error;
+    }
+  }
+
+  /**
+   * Get all sessions belonging to a team.
+   * @param teamUuid - UUID of the team
+   * @returns Array of session data
+   */
+  async teamGetSessions(teamUuid: string): Promise<SessionData[]> {
+    const { data, error } = await this.client
+      .from("sessions")
+      .select(
+        "uuid, title, agent_profile_uuid, workspace, updated_at, user_uuid"
+      )
+      .eq("team_uuid", teamUuid);
+
+    if (error) {
+      throw error;
+    }
+
+    return data.map((session) => ({
+      session_uuid: session.uuid,
+      title: session.title,
+      team_uuid: teamUuid,
+      agent_profile_uuid: session.agent_profile_uuid,
+      workspace: session.workspace || undefined,
+      updated_at: session.updated_at || new Date().toISOString(),
+      user_uuid: session.user_uuid,
+    }));
+  }
+
+  createTypedClient<T extends DbClientBase>(
+    ctor: new (client: SupabaseClient) => T
+  ): T {
+    return new ctor(this.client);
+  }
+}