@xalia/agent 0.6.10 → 0.6.11

package/src/chat/protocol/messages.ts

@@ -1,899 +0,0 @@
-import { Tool, Resource } from "@modelcontextprotocol/sdk/types.js";
-
-import {
-  AgentPreferences,
-  McpServerBrief,
-  McpServerConfiguration,
-  SavedAgentProfile,
-} from "@xalia/xmcp/sdk";
-
-import {
-  TeamRole,
-  TeamInfo,
-  TeamParticipant,
-  UserMessageData,
-  SessionDescriptor,
-  CustomMcpServerDescriptor,
-} from "../data/dataModels";
-import { SessionFileDescriptor } from "../../agent/tools/fileManager";
-import {
-  AssistantMessageParam,
-  MessageParam,
-  MessageToolCall,
-  ToolMessageParam,
-} from "../../agent/llm";
-import { ResourceContent } from "../../agent/mcpServerManager";
-
-export interface ClientToServerBase {
-  type: string;
-  client_message_id: string; // TODO: hide by putting on ClientToServer?
-}
-
-// Session-level messages all have a `session_id`
-export 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;
-  model?: 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 ClientControlAddCustomMcpServer = {
-  type: "control_add_custom_mcp_server";
-  server_name: string;
-  description: string;
-  url: string;
-};
-
-export type ClientControlRemoveCustomMcpServer = {
-  type: "control_remove_custom_mcp_server";
-  server_name: string;
-};
-
-export type ClientControlRefinePrompt = {
-  type: "control_refine_prompt";
-  prompt: string;
-} & ClientToServerBase;
-
-export type ClientControlMessage =
-  | ClientControlAgentProfileCreate
-  | ClientControlAgentProfileDelete
-  | ClientControlGetSessionList
-  | ClientControlSessionCreate
-  | ClientControlSessionJoin
-  | ClientControlTeamCreate
-  | ClientControlSessionDelete
-  | ClientControlAddTeamUser
-  | ClientControlRemoveTeamUser
-  | ClientControlAddCustomMcpServer
-  | ClientControlRemoveCustomMcpServer
-  | ClientControlRefinePrompt;
-
-//
-// Messages for specific sessions
-//
-
-export type ClientUserMessage = {
-  type: "msg";
-  race_mode?: string;
-} & UserMessageData;
-
-/// Signal any currently running agent to stop
-export type ClientStop = {
-  type: "stop";
-};
-
-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 ClientSessionFileGetContent = {
-  type: "session_file_get_content";
-  name: string;
-};
-
-export type ClientSessionFileDelete = {
-  type: "session_file_delete";
-  name: string;
-};
-
-export type ClientSessionFilePutContent = {
-  type: "session_file_put_content";
-  name?: string;
-  summary?: string;
-  data_url: string;
-};
-
-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 ClientSetAgentPaused = {
-  type: "set_agent_paused";
-  paused: boolean;
-};
-
-export type ClientGetMcpResource = {
-  type: "get_mcp_resource";
-  client_message_id: string;
-  server_name: string; // server name
-  uri: string; // uri on server
-};
-
-export type ClientSetMcpServerConfig = {
-  type: "set_mcp_server_config";
-  server_name: string;
-  config?: McpServerConfiguration;
-};
-
-export type ClientShareSession = {
-  type: "share_session";
-};
-
-export type ClientRaceModeResult = {
-  type: "race_mode_result";
-  message_id: string;
-  result: string;
-} & UserMessageData;
-
-export type ClientSessionMessageData =
-  | ClientUserMessage
-  | ClientStop
-  | ClientSetWorkspace
-  | ClientAddMcpServer
-  | ClientRemoveMcpServer
-  | ClientEnableMcpServerTool
-  | ClientDisableMcpServerTool
-  | ClientEnableAllMcpServerTools
-  | ClientDisableAllMcpServerTools
-  | ClientToolCallApprovalResult
-  | ClientSessionFileGetContent
-  | ClientSessionFileDelete
-  | ClientSessionFilePutContent
-  | ClientSetAutoApproval
-  | ClientSetSystemPrompt
-  | ClientSetModel
-  | ClientSetAgentPaused
-  | ClientGetMcpResource
-  | ClientSetMcpServerConfig
-  | ClientShareSession
-  | ClientRaceModeResult;
-
-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":
-    case "control_add_custom_mcp_server":
-    case "control_remove_custom_mcp_server":
-    case "control_refine_prompt":
-      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;
-  agent_paused: boolean;
-} & 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: MessageParam[];
-} & ServerSessionMessage;
-
-/**
- * Message from the server, informing us of a message in the chat history
- */
-export type ServerUserMessage = {
-  type: "user_msg";
-  user_uuid: string;
-  user_nickname: string;
-  message_idx: number;
-  race_mode?: string;
-} & UserMessageData &
-  ServerSessionMessage;
-
-export type ServerAgentMessage = {
-  type: "agent_msg";
-  message: AssistantMessageParam;
-  message_idx: number;
-} & ServerSessionMessage;
-
-export type ServerAgentMessageChunk = {
-  type: "agent_msg_chunk";
-  message: string;
-  message_idx: number;
-  end: boolean;
-  alt?: string;
-} & ServerSessionMessage;
-
-export type ServerReasoningChunk = {
-  type: "agent_reasoning_chunk";
-  reasoning: string;
-  alt?: string;
-} & 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;
-
-// Note: ChatCompletionMessageToolCall contains the tool call id so we don't
-// need an extra id field.
-export type ServerToolCall = {
-  type: "tool_call";
-  tool_call: MessageToolCall;
-  alt?: string;
-} & ServerSessionMessage;
-
-export type ServerToolCallApprovalResult = {
-  type: "tool_call_approval_result";
-  id: string;
-  result: boolean;
-  alt?: string;
-} & ServerSessionMessage;
-
-export type ServerToolCallResult = {
-  type: "tool_call_result";
-  message_idx: number;
-  result: ToolMessageParam;
-  alt?: string;
-} & 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
-  | ServerToolAutoApprovalSet
-  | ServerToolCall
-  | ServerToolCallApprovalResult
-  | ServerToolCallResult
-  | ServerAuthenticationStarted
-  | ServerAuthenticationFinished
-  | ServerUserTyping;
-
-//
-// session-file related messages
-//
-
-export type ServerSessionFileChanged = {
-  type: "session_file_changed";
-  descriptor: SessionFileDescriptor;
-  new_file: boolean;
-} & ServerSessionMessage;
-
-export type ServerSessionFileDeleted = {
-  type: "session_file_deleted";
-  name: string;
-} & ServerSessionMessage;
-
-export type ServerSessionFileContent = {
-  type: "session_file_content";
-  name: string;
-  data_url: string;
-  client_message_id: string;
-} & ServerSessionMessage;
-
-export type ServerSessionFileMessage =
-  | ServerSessionFileChanged
-  | ServerSessionFileDeleted
-  | ServerSessionFileContent;
-
-//
-// state updates
-//
-export type ServerMcpServerAdded = {
-  type: "mcp_server_added";
-  server_name: string;
-  tools: Tool[];
-  resources: Resource[];
-  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 ServerAgentPaused = {
-  type: "agent_paused";
-  paused: boolean;
-} & 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 ServerSessionShared = {
-  type: "session_shared";
-  access_token: string;
-  client_message_id: string;
-} & ServerSessionMessage;
-
-export type ServerMcpResource = {
-  type: "mcp_resource";
-  client_message_id: string;
-  server_name: string;
-  contents: ResourceContent[];
-} & ServerSessionMessage;
-
-export type ServerContextUsage = {
-  type: "context_usage";
-  used_tokens: number;
-  max_tokens: number;
-} & ServerSessionMessage;
-
-export type ServerToClientStateUpdate =
-  | ServerMcpServerAdded
-  | ServerMcpServerRemoved
-  | ServerMcpServerToolEnabled
-  | ServerMcpServerToolDisabled
-  | ServerSystemPromptUpdated
-  | ServerModelUpdated
-  | ServerAgentPaused
-  | ServerUserAdded
-  | ServerUserRemoved
-  | ServerSessionShared
-  | ServerMcpResource
-  | ServerContextUsage;
-
-//
-// actions
-//
-
-export type ServerAuthenticate = {
-  type: "authenticate";
-  url: string;
-  display_name: string;
-} & ServerSessionMessage;
-
-export type ServerApproveToolCall = {
-  type: "approve_tool_call";
-  id: string;
-  tool_call: MessageToolCall;
-  alt?: string;
-} & ServerSessionMessage;
-
-export type ServerRenderHTML = {
-  type: "render_html";
-  html: string;
-} & ServerSessionMessage;
-
-export type ServerEditorUpdate = {
-  type: "editor_update";
-  operation: "replace" | "append" | "prepend" | "replace_selection";
-  content: string;
-  format: "markdown";
-  selectionId?: string;
-} & ServerSessionMessage;
-
-export type ServerRaceModeGetResult = {
-  type: "race_mode_get_result";
-  message_id: string;
-  alts: string[];
-} & ServerSessionMessage;
-
-export type ServerToClientActions =
-  | ServerAuthenticate
-  | ServerApproveToolCall
-  | ServerRenderHTML
-  | ServerEditorUpdate
-  | ServerRaceModeGetResult;
-
-//
-// 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>;
-};
-
-/**
- * Team members have been updated (added or removed).
- */
-export type ServerControlTeamMembersUpdated = {
-  type: "control_team_members_updated";
-  team_uuid: string;
-  members: Array<TeamParticipant>;
-};
-
-/**
- * List of available sessions for user
- */
-export type ServerControlSessionList = {
-  type: "control_session_list";
-  user_sessions: Array<SessionDescriptor>;
-  user_agents: Array<SavedAgentProfile>;
-  team_sessions: Array<TeamInfo>;
-  custom_mcp_servers: Record<string, CustomMcpServerDescriptor>;
-} & 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;
-
-export type ServerControlCustomMcpServerAdded = {
-  type: "control_custom_mcp_server_added";
-  server_name: string;
-  url: string;
-};
-
-export type ServerControlCustomMcpServerRemoved = {
-  type: "control_custom_mcp_server_removed";
-  server_name: string;
-};
-
-export type ServerControlRefinePromptResult = {
-  type: "control_refine_prompt_result";
-  refined_prompt: string;
-  client_message_id: string;
-};
-
-/**
- * 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
-  | ServerControlTeamMembersUpdated
-  | ServerControlCustomMcpServerAdded
-  | ServerControlCustomMcpServerRemoved
-  | ServerControlRefinePromptResult
-  | ServerControlError;
-
-export type ServerSessionScopedMessage =
-  | ServerSessionError
-  | ServerSessionInfo
-  | ServerUserMessage
-  | ServerAgentMessage
-  | ServerAgentMessageChunk
-  | ServerReasoningChunk
-  | ServerToClientNotifications
-  | ServerSessionFileMessage
-  | 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_team_members_updated":
-    case "control_custom_mcp_server_added":
-    case "control_custom_mcp_server_removed":
-    case "control_refine_prompt_result":
-    case "control_error":
-      return true;
-    default: {
-      const _: never = msg;
-      return false;
-    }
-  }
-}
-
-export function isServerSessionFileMessage(
-  message: ServerToClient
-): message is ServerSessionFileMessage {
-  const msg = message as ServerSessionFileMessage;
-  switch (msg.type) {
-    case "session_file_changed":
-    case "session_file_deleted":
-    case "session_file_content":
-      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 "agent_reasoning_chunk":
-    case "user_joined":
-    case "user_left":
-    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 "session_file_changed":
-    case "session_file_deleted":
-    case "session_file_content":
-    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 "agent_paused":
-    case "user_added":
-    case "user_removed":
-    case "authenticate":
-    case "approve_tool_call":
-    case "render_html":
-    case "editor_update":
-    case "race_mode_get_result":
-    case "session_shared":
-    case "mcp_resource":
-    case "context_usage":
-      return true;
-
-    default: {
-      const _: never = msg;
-      return false;
-    }
-  }
-}
-
-export function decodeAssistantMessageParam(
-  msg: AssistantMessageParam
-): 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;
-}