@xalia/agent 0.5.8 → 0.6.1

package/src/chat/protocol/messages.ts

@@ -0,0 +1,682 @@
+import {
+  ChatCompletionMessageParam,
+  ChatCompletionAssistantMessageParam,
+  ChatCompletionToolMessageParam,
+  ChatCompletionMessageToolCall,
+} from "openai/resources.mjs";
+import { Tool } from "@modelcontextprotocol/sdk/types.js";
+
+import {
+  AgentPreferences,
+  McpServerBrief,
+  McpServerConfiguration,
+  SavedAgentProfile,
+} from "@xalia/xmcp/sdk";
+import {
+  TeamRole,
+  SessionData,
+  TeamInfo,
+  TeamParticipant,
+  UserMessageData,
+} from "../data/dataModels";
+
+interface ClientToServerBase {
+  type: string;
+  client_message_id: string; // TODO: hide by putting on ClientToServer?
+}
+
+// Session-level messages all have a `session_id`
+interface ClientSessionMessageBase extends ClientToServerBase {
+  session_id: string;
+}
+
+//
+// Session-management messages
+//
+
+export type ClientControlAgentProfileCreate = {
+  type: "control_agent_profile_create";
+  title: string;
+  user_uuid?: string | undefined;
+  team_uuid?: string | undefined;
+  template_name?: string | undefined;
+};
+
+export type ClientControlAgentProfileDelete = {
+  type: "control_agent_profile_delete";
+  agent_profile_uuid: string;
+};
+
+/**
+ * Create a new team with initial members.
+ * Initial_members doesn't need to include the owner.
+ */
+export type ClientControlTeamCreate = {
+  type: "control_team_create";
+  team_name: string;
+  initial_members: Array<string>;
+} & ClientToServerBase;
+
+/**
+ * Request list of available sessions for the user
+ */
+export type ClientControlGetSessionList = {
+  type: "control_get_session_list";
+} & ClientToServerBase;
+
+/**
+ * Create a new session
+ */
+export type ClientControlSessionCreate = {
+  type: "control_session_create";
+  title: string;
+  agent_profile_id?: string;
+  team_id?: string;
+} & ClientToServerBase;
+
+/**
+ * Join an existing session
+ * Note: Uses target_session_id to avoid conflict with session_id: never
+ * from base
+ */
+export type ClientControlSessionJoin = {
+  type: "control_session_join";
+  target_session_id: string;
+} & ClientToServerBase;
+
+/**
+ * Delete a session
+ */
+export type ClientControlSessionDelete = {
+  type: "control_session_delete";
+  target_session_id: string;
+} & ClientToServerBase;
+
+/**
+ * Add a user to a team
+ */
+export type ClientControlAddTeamUser = {
+  type: "control_add_team_user";
+  user_uuid_or_email: string;
+  target_team_id: string;
+} & ClientToServerBase;
+
+/**
+ * Remove a user from a team
+ */
+export type ClientControlRemoveTeamUser = {
+  type: "control_remove_team_user";
+  user_uuid_or_email: string;
+  target_team_id: string;
+} & ClientToServerBase;
+
+export type ClientControlMessage =
+  | ClientControlAgentProfileCreate
+  | ClientControlAgentProfileDelete
+  | ClientControlGetSessionList
+  | ClientControlSessionCreate
+  | ClientControlSessionJoin
+  | ClientControlTeamCreate
+  | ClientControlSessionDelete
+  | ClientControlAddTeamUser
+  | ClientControlRemoveTeamUser;
+
+//
+// Messages for specific sessions
+//
+
+export type ClientUserMessage = {
+  type: "msg";
+} & UserMessageData;
+
+export type ClientSetWorkspace = {
+  type: "set_workspace";
+} & UserMessageData;
+
+export type ClientAddMcpServer = {
+  type: "add_mcp_server";
+  server_name: string;
+  enable_all: boolean;
+};
+
+export type ClientRemoveMcpServer = {
+  type: "remove_mcp_server";
+  server_name: string;
+};
+
+export type ClientEnableMcpServerTool = {
+  type: "enable_mcp_server_tool";
+  server_name: string;
+  tool: string;
+};
+
+export type ClientDisableMcpServerTool = {
+  type: "disable_mcp_server_tool";
+  server_name: string;
+  tool: string;
+};
+
+export type ClientEnableAllMcpServerTools = {
+  type: "enable_all_mcp_server_tools";
+  server_name: string;
+};
+
+export type ClientDisableAllMcpServerTools = {
+  type: "disable_all_mcp_server_tools";
+  server_name: string;
+};
+
+export type ClientToolCallApprovalResult = {
+  type: "tool_call_approval_result";
+  id: string;
+  result: boolean;
+  auto_approve: boolean;
+};
+
+export type ClientSetAutoApproval = {
+  type: "set_auto_approval";
+  server_name: string;
+  tool: string;
+  auto_approve: boolean;
+};
+
+export type ClientSetSystemPrompt = {
+  type: "set_system_prompt";
+  system_prompt: string;
+};
+
+export type ClientSetModel = {
+  type: "set_model";
+  model: string;
+};
+
+export type ClientSetMcpServerConfig = {
+  type: "set_mcp_server_config";
+  server_name: string;
+  config?: McpServerConfiguration;
+};
+
+export type ClientSessionMessageData =
+  | ClientUserMessage
+  | ClientSetWorkspace
+  | ClientAddMcpServer
+  | ClientRemoveMcpServer
+  | ClientEnableMcpServerTool
+  | ClientDisableMcpServerTool
+  | ClientEnableAllMcpServerTools
+  | ClientDisableAllMcpServerTools
+  | ClientToolCallApprovalResult
+  | ClientSetAutoApproval
+  | ClientSetSystemPrompt
+  | ClientSetModel
+  | ClientSetMcpServerConfig;
+
+export type ClientSessionMessage = ClientSessionMessageBase &
+  ClientSessionMessageData;
+
+//
+// Client Message Union Types
+//
+
+export type ClientToServer = ClientControlMessage | ClientSessionMessage;
+
+export function isClientControlMessage(
+  message: ClientToServer
+): message is ClientControlMessage {
+  const msg = message as ClientControlMessage;
+  switch (msg.type) {
+    case "control_agent_profile_create":
+    case "control_agent_profile_delete":
+    case "control_get_session_list":
+    case "control_session_create":
+    case "control_session_delete":
+    case "control_session_join":
+    case "control_team_create":
+    case "control_add_team_user":
+    case "control_remove_team_user":
+      return true;
+    default: {
+      const _: never = msg;
+      return false;
+    }
+  }
+}
+
+// TODO: factor this as above
+
+/**
+ * Base interface for messages from server to client scoped to a session
+ */
+interface ServerSessionMessage {
+  session_id: string;
+}
+
+/**
+ * Base interface for connection-level server responses needing correlation
+ */
+interface ControlResponseMessage {
+  client_message_id: string; // Echo back client's message ID for correlation
+}
+
+///
+/// Server -> Client Messages
+///
+
+/**
+ * Error in response to an invalid request from the client
+ * with a sesion scoped.
+ */
+export type ServerSessionError = {
+  type: "session_error";
+  message: string;
+  client_message_id?: string;
+} & ServerSessionMessage;
+
+/**
+ * Session info can be requested normally, or when the client is
+ * joining a session or creating a new session.
+ */
+export type ServerSessionInfo = {
+  type: "session_info";
+  owner_uuid: string;
+  title: string;
+  saved_agent_profile: SavedAgentProfile;
+  workspace: UserMessageData | undefined;
+  updated_at: string;
+  participants: TeamParticipant[];
+  mcp_server_briefs: McpServerBrief[];
+  agent_preferences: AgentPreferences;
+  client_message_id: string;
+  team_uuid: string | undefined;
+} & ServerSessionMessage;
+
+/**
+ * (from server) Chat history
+ */
+export type ServerHistory = {
+  type: "history";
+  /// Conversation history in the form we expect.  The `name` attribute of
+  /// `ChatCompletionUserMessageParam` (role: "user") holds the original
+  /// message sender.
+  messages: ChatCompletionMessageParam[];
+} & ServerSessionMessage;
+
+/**
+ * Message from the server, informing us of a message in the chat history
+ */
+export type ServerUserMessage = {
+  type: "user_msg";
+  user_uuid: string;
+  message_idx: number;
+} & UserMessageData &
+  ServerSessionMessage;
+
+export type ServerAgentMessage = {
+  type: "agent_msg";
+  message: ChatCompletionAssistantMessageParam;
+  message_idx: number;
+} & ServerSessionMessage;
+
+export type ServerAgentMessageChunk = {
+  type: "agent_msg_chunk";
+  message: string;
+  message_idx: number;
+  end: boolean;
+} & ServerSessionMessage;
+
+//
+// Notifications
+///
+
+export type ServerUserJoined = {
+  type: "user_joined";
+  user_uuid: string;
+  user_name: string;
+} & ServerSessionMessage;
+
+export type ServerUserLeft = {
+  type: "user_left";
+  user_uuid: string;
+} & ServerSessionMessage;
+
+export type ServerSessionUpdate = {
+  type: "session_update";
+  title?: string;
+  participants?: TeamParticipant[];
+} & ServerSessionMessage;
+
+// Note: ChatCompletionMessageToolCall contains the tool call id so we don't
+// need an extra id field.
+export type ServerToolCall = {
+  type: "tool_call";
+  tool_call: ChatCompletionMessageToolCall;
+} & ServerSessionMessage;
+
+export type ServerToolCallApprovalResult = {
+  type: "tool_call_approval_result";
+  id: string;
+  result: boolean;
+} & ServerSessionMessage;
+
+export type ServerToolCallResult = {
+  type: "tool_call_result";
+  message_idx: number;
+  result: ChatCompletionToolMessageParam;
+} & ServerSessionMessage;
+
+export type ServerToolAutoApprovalSet = {
+  type: "tool_auto_approval_set";
+  server_name: string;
+  tool: string;
+  auto_approve: boolean;
+} & ServerSessionMessage;
+
+// TODO: include mcp server name
+
+export type ServerAuthenticationStarted = {
+  type: "authentication_started";
+  url: string;
+} & ServerSessionMessage;
+
+// TODO: include richer results (success/failure/timeout)
+
+export type ServerAuthenticationFinished = {
+  type: "authentication_finished";
+  url: string;
+  result: boolean;
+} & ServerSessionMessage;
+
+export type ServerUserTyping = {
+  type: "user_typing";
+  user_uuid: string;
+} & ServerSessionMessage;
+
+export type ServerToClientNotifications =
+  | ServerUserJoined
+  | ServerUserLeft
+  | ServerSessionUpdate
+  | ServerToolAutoApprovalSet
+  | ServerToolCall
+  | ServerToolCallApprovalResult
+  | ServerToolCallResult
+  | ServerAuthenticationStarted
+  | ServerAuthenticationFinished
+  | ServerUserTyping;
+
+//
+// state updates
+//
+
+/**
+ * A new team has been created.
+ * The members array contains the members of the team.
+ * The members array contains undefined for failed lookups.
+ */
+export type ServerMcpServerAdded = {
+  type: "mcp_server_added";
+  server_name: string;
+  tools: Tool[];
+  enabled_tools: string[];
+} & ServerSessionMessage;
+
+export type ServerMcpServerRemoved = {
+  type: "mcp_server_removed";
+  server_name: string;
+} & ServerSessionMessage;
+
+export type ServerMcpServerToolEnabled = {
+  type: "mcp_server_tool_enabled";
+  server_name: string;
+  tool: string;
+} & ServerSessionMessage;
+
+export type ServerMcpServerToolDisabled = {
+  type: "mcp_server_tool_disabled";
+  server_name: string;
+  tool: string;
+} & ServerSessionMessage;
+
+export type ServerSystemPromptUpdated = {
+  type: "system_prompt_updated";
+  system_prompt: string;
+} & ServerSessionMessage;
+
+export type ServerModelUpdated = {
+  type: "model_updated";
+  model: string;
+} & ServerSessionMessage;
+
+export type ServerUserAdded = {
+  type: "user_added";
+  user_uuid: string;
+  nickname: string;
+  email: string;
+  role: TeamRole;
+} & ServerSessionMessage;
+
+export type ServerUserRemoved = {
+  type: "user_removed";
+  user_uuid: string;
+} & ServerSessionMessage;
+
+export type ServerToClientStateUpdate =
+  | ServerMcpServerAdded
+  | ServerMcpServerRemoved
+  | ServerMcpServerToolEnabled
+  | ServerMcpServerToolDisabled
+  | ServerSystemPromptUpdated
+  | ServerModelUpdated
+  | ServerUserAdded
+  | ServerUserRemoved;
+
+//
+// actions
+//
+
+export type ServerAuthenticate = {
+  type: "authenticate";
+  url: string;
+  display_name: string;
+} & ServerSessionMessage;
+
+export type ServerApproveToolCall = {
+  type: "approve_tool_call";
+  id: string;
+  tool_call: ChatCompletionMessageToolCall;
+} & ServerSessionMessage;
+
+export type ServerRenderHTML = {
+  type: "render_html";
+  html: string;
+} & ServerSessionMessage;
+
+export type ServerToClientActions =
+  | ServerAuthenticate
+  | ServerApproveToolCall
+  | ServerRenderHTML;
+
+//
+// Control-level messages (session management)
+//
+
+export type ServerControlAgentProfileCreated = {
+  type: "control_agent_profile_created";
+  profile: SavedAgentProfile;
+};
+
+export type ServerControlAgentProfileDeleted = {
+  type: "control_agent_profile_deleted";
+  profile_uuid: string;
+};
+
+/**
+ * A new team has been created.
+ * The members array contains the members of the team.
+ * The members array contains undefined for failed lookups.
+ */
+export type ServerControlTeamCreated = {
+  type: "control_team_created";
+  team_uuid: string;
+  team_owner_uuid: string;
+  team_name: string;
+  members: Array<TeamParticipant>;
+  failed_lookups: Array<string>;
+};
+
+/**
+ * List of available sessions for user
+ */
+export type ServerControlSessionList = {
+  type: "control_session_list";
+  user_sessions: Array<SessionData>;
+  user_agents: Array<SavedAgentProfile>;
+  team_sessions: Array<TeamInfo>;
+} & ControlResponseMessage;
+
+/**
+ * Confirmation of session leave, for example,
+ * a user is kicked from a session.
+ */
+export type ServerControlSessionLeft = {
+  type: "control_session_left";
+  session_id: string;
+} & ControlResponseMessage;
+
+/**
+ * Confirmation of session delete.
+ */
+export type ServerControlSessionDeleted = {
+  type: "control_session_deleted";
+  session_id: string;
+  agent_profile_uuid: string;
+  team_uuid?: string;
+} & ControlResponseMessage;
+
+/**
+ * Connection-level errors
+ * Error in response to an invalid request from the client
+ * with a connection scoped.
+ */
+export type ServerControlError = {
+  type: "control_error";
+  message: string;
+  client_message_id?: string;
+};
+
+export type ServerControlMessage =
+  | ServerControlSessionList
+  | ServerControlSessionLeft
+  | ServerControlSessionDeleted
+  | ServerControlAgentProfileCreated
+  | ServerControlAgentProfileDeleted
+  | ServerControlTeamCreated
+  | ServerControlError;
+
+export type ServerSessionScopedMessage =
+  | ServerSessionError
+  | ServerSessionInfo
+  | ServerUserMessage
+  | ServerAgentMessage
+  | ServerAgentMessageChunk
+  | ServerToClientNotifications
+  | ServerToClientStateUpdate
+  | ServerToClientActions;
+
+export type ServerToClient = ServerControlMessage | ServerSessionScopedMessage;
+
+//
+// Type guard helper functions
+//
+
+export function isServerControlMessage(
+  message: ServerToClient
+): message is ServerControlMessage {
+  const msg = message as ServerControlMessage;
+  switch (msg.type) {
+    case "control_agent_profile_created":
+    case "control_agent_profile_deleted":
+    case "control_session_list":
+    case "control_session_left":
+    case "control_session_deleted":
+    case "control_team_created":
+    case "control_error":
+      return true;
+    default: {
+      const _: never = msg;
+      return false;
+    }
+  }
+}
+
+/**
+ * Type guard to check if a ServerToClient message is a session-scoped message
+ */
+export function isServerSessionScopedMessage(
+  message: ServerToClient
+): message is ServerSessionScopedMessage {
+  const msg = message as ServerSessionScopedMessage;
+  switch (msg.type) {
+    case "session_error":
+    case "session_info":
+    case "user_msg":
+    case "agent_msg":
+    case "agent_msg_chunk":
+    case "user_joined":
+    case "user_left":
+    case "session_update":
+    case "tool_auto_approval_set":
+    case "tool_call":
+    case "tool_call_approval_result":
+    case "tool_call_result":
+    case "authentication_started":
+    case "authentication_finished":
+    case "user_typing":
+    case "mcp_server_added":
+    case "mcp_server_removed":
+    case "mcp_server_tool_enabled":
+    case "mcp_server_tool_disabled":
+    case "system_prompt_updated":
+    case "model_updated":
+    case "user_added":
+    case "user_removed":
+    case "authenticate":
+    case "approve_tool_call":
+    case "render_html":
+      return true;
+    default: {
+      const _: never = msg;
+      return false;
+    }
+  }
+}
+
+export function decodeAssistantMessageParam(
+  msg: ChatCompletionAssistantMessageParam
+): string {
+  let text = "";
+
+  if (msg.audio) {
+    throw new Error("decodeAssistantMessageParam; audio unimplemented");
+  }
+
+  if (msg.content) {
+    if (typeof msg.content === "string") {
+      text = msg.content;
+    } else if (msg.content instanceof Array) {
+      for (const c of msg.content) {
+        switch (c.type) {
+          case "text":
+            text += c.text;
+            break;
+          case "refusal":
+            text += c.refusal;
+            break;
+          default:
+            throw Error("unexpected AssistantMessageParam.content entry");
+        }
+      }
+    }
+  }
+
+  return text;
+}