microsoft-agents-hosting-core 0.4.0.dev18__py3-none-any.whl → 0.5.0.dev3__py3-none-any.whl

microsoft_agents/hosting/core/_oauth/_flow_state.py

@@ -3,7 +3,7 @@
 
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime, timezone
 from enum import Enum
 from typing import Optional
 
@@ -60,7 +60,7 @@ class _FlowState(BaseModel, StoreItem):
         return _FlowState.model_validate(json_data)
 
     def is_expired(self) -> bool:
-        return datetime.now().timestamp() >= self.expiration
+        return datetime.now(timezone.utc).timestamp() >= self.expiration
 
     def reached_max_attempts(self) -> bool:
         return self.attempts_remaining <= 0

microsoft_agents/hosting/core/_oauth/_oauth_flow.py

@@ -6,7 +6,7 @@ from __future__ import annotations
 import logging
 
 from pydantic import BaseModel
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Optional
 
 from microsoft_agents.activity import (
@@ -30,7 +30,6 @@ class _FlowResponse(BaseModel):
     flow_error_tag: _FlowErrorTag = _FlowErrorTag.NONE
     token_response: Optional[TokenResponse] = None
     sign_in_resource: Optional[SignInResource] = None
-    continuation_activity: Optional[Activity] = None
 
 
 class _OAuthFlow:
@@ -112,7 +111,7 @@ class _OAuthFlow:
         """Get the user token based on the context.
 
         Args:
-            magic_code (str, optional): Defaults to None. The magic code for user authentication.
+            magic_code (str, Optional): Defaults to None. The magic code for user authentication.
 
         Returns:
             TokenResponse
@@ -137,7 +136,7 @@ class _OAuthFlow:
         if token_response:
             logger.info("User token obtained successfully: %s", token_response)
             self._flow_state.expiration = (
-                datetime.now().timestamp() + self._default_flow_duration
+                datetime.now(timezone.utc).timestamp() + self._default_flow_duration
             )
             self._flow_state.tag = _FlowStateTag.COMPLETE
 
@@ -183,20 +182,8 @@ class _OAuthFlow:
         Notes:
             The flow state is reset if a token is not obtained from cache.
         """
-        token_response = await self.get_user_token()
-        if token_response:
-            return _FlowResponse(
-                flow_state=self._flow_state, token_response=token_response
-            )
 
         logger.debug("Starting new OAuth flow")
-        self._flow_state.tag = _FlowStateTag.BEGIN
-        self._flow_state.expiration = (
-            datetime.now().timestamp() + self._default_flow_duration
-        )
-
-        self._flow_state.attempts_remaining = self._max_attempts
-        self._flow_state.continuation_activity = activity.model_copy()
 
         token_exchange_state = TokenExchangeState(
             connection_name=self._abs_oauth_connection_name,
@@ -205,16 +192,33 @@ class _OAuthFlow:
             ms_app_id=self._ms_app_id,
         )
 
-        sign_in_resource = (
-            await self._user_token_client.agent_sign_in.get_sign_in_resource(
-                state=token_exchange_state.get_encoded_state()
+        res = await self._user_token_client.user_token._get_token_or_sign_in_resource(
+            activity.from_property.id,
+            self._abs_oauth_connection_name,
+            activity.channel_id,
+            token_exchange_state.get_encoded_state(),
+        )
+
+        if res.token_response:
+            logger.info("Skipping flow, user token obtained.")
+            self._flow_state.tag = _FlowStateTag.COMPLETE
+            self._flow_state.expiration = (
+                datetime.now(timezone.utc).timestamp() + self._default_flow_duration
+            )
+            return _FlowResponse(
+                flow_state=self._flow_state, token_response=res.token_response
             )
+
+        self._flow_state.tag = _FlowStateTag.BEGIN
+        self._flow_state.expiration = (
+            datetime.now(timezone.utc).timestamp() + self._default_flow_duration
         )
+        self._flow_state.attempts_remaining = self._max_attempts
 
-        logger.debug("Sign-in resource obtained successfully: %s", sign_in_resource)
+        logger.debug("Sign-in resource obtained successfully: %s", res.sign_in_resource)
 
         return _FlowResponse(
-            flow_state=self._flow_state, sign_in_resource=sign_in_resource
+            flow_state=self._flow_state, sign_in_resource=res.sign_in_resource
         )
 
     async def _continue_from_message(
@@ -299,7 +303,7 @@ class _OAuthFlow:
         else:
             self._flow_state.tag = _FlowStateTag.COMPLETE
             self._flow_state.expiration = (
-                datetime.now().timestamp() + self._default_flow_duration
+                datetime.now(timezone.utc).timestamp() + self._default_flow_duration
             )
             logger.debug(
                 "OAuth flow completed successfully, got TokenResponse: %s",
@@ -310,7 +314,6 @@ class _OAuthFlow:
             flow_state=self._flow_state.model_copy(),
             flow_error_tag=flow_error_tag,
             token_response=token_response,
-            continuation_activity=self._flow_state.continuation_activity,
         )
 
     async def begin_or_continue_flow(self, activity: Activity) -> _FlowResponse:

microsoft_agents/hosting/core/activity_handler.py

@@ -38,7 +38,7 @@ class ActivityHandler(Agent):
         in order to process an inbound :class:`microsoft_agents.activity.Activity`.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
 
         :returns: A task that represents the work queued to execute
 
@@ -143,7 +143,7 @@ class ActivityHandler(Agent):
         :meth:`on_turn()` is used.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
 
         .. remarks::
@@ -216,7 +216,7 @@ class ActivityHandler(Agent):
         :meth:`on_turn()` is used.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
 
         :returns: A task that represents the work queued to execute
 
@@ -382,7 +382,7 @@ class ActivityHandler(Agent):
         ActivityTypes.typing activities, such as the conversational logic.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
         """
         return
@@ -395,7 +395,7 @@ class ActivityHandler(Agent):
         ActivityTypes.InstallationUpdate activities.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
         """
         if turn_context.activity.action in ("add", "add-upgrade"):
@@ -412,7 +412,7 @@ class ActivityHandler(Agent):
         ActivityTypes.InstallationUpdate activities with 'action' set to 'add'.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
         """
         return
@@ -425,7 +425,7 @@ class ActivityHandler(Agent):
         ActivityTypes.InstallationUpdate activities with 'action' set to 'remove'.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
         """
         return
@@ -439,7 +439,7 @@ class ActivityHandler(Agent):
         If overridden, this method could potentially respond to any of the other activity types.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
 
         :returns: A task that represents the work queued to execute
 
@@ -456,7 +456,7 @@ class ActivityHandler(Agent):
         Registers an activity event handler for the _invoke_ event, emitted for every incoming event activity.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
 
         :returns: A task that represents the work queued to execute
         """
@@ -492,7 +492,7 @@ class ActivityHandler(Agent):
         By default, this method does nothing.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
 
         :returns: A task that represents the work queued to execute
         """
@@ -508,7 +508,7 @@ class ActivityHandler(Agent):
         calls this method.
 
         :param turn_context: A context object for this turn.
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :param invoke_value: A string-typed object from the incoming activity's value.
         :type invoke_value: :class:`microsoft_agents.activity.adaptive_card_invoke_value.AdaptiveCardInvokeValue`
         :return: The HealthCheckResponse object

microsoft_agents/hosting/core/app/agent_application.py

@@ -221,14 +221,14 @@ class AgentApplication(Agent, Generic[StateT]):
         :param handler: A function that takes a TurnContext and a TurnState and returns an Awaitable.
         :type handler: RouteHandler[StateT]
         :param is_invoke: Whether the route is for an invoke activity, defaults to False
-        :type is_invoke: bool, optional
+        :type is_invoke: bool, Optional
         :param is_agentic: Whether the route is for an agentic request, defaults to False. For agentic requests
             the selector will include a new check for `context.activity.is_agentic_request()`.
-        :type is_agentic: bool, optional
+        :type is_agentic: bool, Optional
         :param rank: The rank of the route, defaults to RouteRank.DEFAULT
-        :type rank: RouteRank, optional
+        :type rank: RouteRank, Optional
         :param auth_handlers: A list of authentication handler IDs to use for this route, defaults to None
-        :type auth_handlers: Optional[list[str]], optional
+        :type auth_handlers: Optional[list[str]], Optional
         :raises ApplicationError: If the selector or handler are not valid.
         """
         if not selector or not handler:

microsoft_agents/hosting/core/app/input_file.py

@@ -16,10 +16,12 @@ from microsoft_agents.hosting.core import TurnContext
 class InputFile:
     """A file sent by the user to the bot.
 
-    Attributes:
-        content (bytes): The downloaded content of the file.
-        content_type (str): The content type of the file.
-        content_url (Optional[str]): Optional. URL to the content of the file.
+    :param content: The downloaded content of the file.
+    :type content: bytes
+    :param content_type: The content type of the file.
+    :type content_type: str
+    :param content_url: Optional. URL to the content of the file.
+    :type content_url: Optional[str]
     """
 
     content: bytes
@@ -29,17 +31,19 @@ class InputFile:
 
 class InputFileDownloader(ABC):
     """
-    A plugin responsible for downloading files relative to the current user's input.
+    Abstract base class for a plugin responsible for downloading files provided by the user.
+
+    Implementations should download any files referenced by the incoming activity and return a
+    list of :class:`InputFile` instances representing the downloaded content.
     """
 
     @abstractmethod
     async def download_files(self, context: TurnContext) -> List[InputFile]:
         """
-        Download any files relative to the current user's input.
-
-        Args:
-            context (TurnContext): Context for the current turn of conversation.
+        Download any files referenced by the incoming activity for the current turn.
 
-        Returns:
-            List[InputFile]: A list of input files.
+        :param context: The turn context for the current request.
+        :type context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
+        :return: A list of downloaded :class:`InputFile` objects.
+        :rtype: list[:class:`microsoft_agents.hosting.core.app.input_file.InputFile`]
         """

microsoft_agents/hosting/core/app/oauth/_handlers/_authorization_handler.py

@@ -43,7 +43,7 @@ class _AuthorizationHandler(ABC):
         :param connection_manager: The connection manager for OAuth providers.
         :type connection_manager: Connections
         :param auth_handlers: Configuration for OAuth providers.
-        :type auth_handlers: dict[str, AuthHandler], optional
+        :type auth_handlers: dict[str, AuthHandler], Optional
         :raises ValueError: When storage is None or no auth handlers provided.
         """
         if not storage:
@@ -75,7 +75,7 @@ class _AuthorizationHandler(ABC):
         :param context: The turn context for the current turn of conversation.
         :type context: TurnContext
         :param scopes: Optional list of scopes to request during sign-in. If None, default scopes will be used.
-        :type scopes: Optional[list[str]], optional
+        :type scopes: Optional[list[str]], Optional
         :return: A SignInResponse indicating the result of the sign-in attempt.
         :rtype: SignInResponse
         """
@@ -92,9 +92,9 @@ class _AuthorizationHandler(ABC):
         :param context: The turn context for the current turn of conversation.
         :type context: TurnContext
         :param exchange_connection: Optional name of the connection to use for token exchange. If None, default connection will be used.
-        :type exchange_connection: Optional[str], optional
+        :type exchange_connection: Optional[str], Optional
         :param exchange_scopes: Optional list of scopes to request during token exchange. If None, default scopes will be used.
-        :type exchange_scopes: Optional[list[str]], optional
+        :type exchange_scopes: Optional[list[str]], Optional
         """
         raise NotImplementedError()
 

microsoft_agents/hosting/core/app/oauth/_handlers/_user_authorization.py

@@ -249,9 +249,9 @@ class _UserAuthorization(_AuthorizationHandler):
         :param context: The turn context for the current turn of conversation.
         :type context: TurnContext
         :param exchange_connection: Optional name of the connection to use for token exchange. If None, default connection will be used.
-        :type exchange_connection: Optional[str], optional
+        :type exchange_connection: Optional[str], Optional
         :param exchange_scopes: Optional list of scopes to request during token exchange. If None, default scopes will be used.
-        :type exchange_scopes: Optional[list[str]], optional
+        :type exchange_scopes: Optional[list[str]], Optional
         """
         flow, _ = await self._load_flow(context)
         input_token_response = await flow.get_user_token()

microsoft_agents/hosting/core/app/oauth/_handlers/agentic_user_authorization.py

@@ -41,7 +41,7 @@ class AgenticUserAuthorization(_AuthorizationHandler):
         :param connection_manager: The connection manager for OAuth providers.
         :type connection_manager: Connections
         :param auth_handlers: Configuration for OAuth providers.
-        :type auth_handlers: dict[str, AuthHandler], optional
+        :type auth_handlers: dict[str, AuthHandler], Optional
         :raises ValueError: When storage is None or no auth handlers provided.
         """
         super().__init__(
@@ -172,9 +172,9 @@ class AgenticUserAuthorization(_AuthorizationHandler):
         :param context: The turn context for the current turn of conversation.
         :type context: TurnContext
         :param exchange_connection: Optional name of the connection to use for token exchange. If None, default connection will be used.
-        :type exchange_connection: Optional[str], optional
+        :type exchange_connection: Optional[str], Optional
         :param exchange_scopes: Optional list of scopes to request during token exchange. If None, default scopes will be used.
-        :type exchange_scopes: Optional[list[str]], optional
+        :type exchange_scopes: Optional[list[str]], Optional
         """
         if not exchange_scopes:
             exchange_scopes = self._handler.scopes or []

microsoft_agents/hosting/core/app/oauth/authorization.py

@@ -59,7 +59,7 @@ class Authorization:
         :param connection_manager: The connection manager for OAuth providers.
         :type connection_manager: Connections
         :param auth_handlers: Configuration for OAuth providers.
-        :type auth_handlers: dict[str, AuthHandler], optional
+        :type auth_handlers: dict[str, AuthHandler], Optional
         :raises ValueError: When storage is None or no auth handlers provided.
         """
         if not storage:

microsoft_agents/hosting/core/channel_adapter.py

@@ -40,7 +40,7 @@ class ChannelAdapter(ABC, ChannelAdapterProtocol):
         Sends a set of activities to the user. An array of responses from the server will be returned.
 
         :param context: The context object for the turn.
-        :type context: :class:`TurnContext`
+        :type context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         :param activities: The activities to send.
         :type activities: list[Activity]
         :return:
@@ -53,7 +53,7 @@ class ChannelAdapter(ABC, ChannelAdapterProtocol):
         Replaces an existing activity.
 
         :param context: The context object for the turn.
-        :type context: :class:`TurnContext`
+        :type context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         :param activity: New replacement activity.
         :type activity: :class:`microsoft_agents.activity.Activity`
         :return:
@@ -68,7 +68,7 @@ class ChannelAdapter(ABC, ChannelAdapterProtocol):
         Deletes an existing activity.
 
         :param context: The context object for the turn.
-        :type context: :class:`TurnContext`
+        :type context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         :param reference: Conversation reference for the activity to delete.
         :type reference: :class:`microsoft_agents.activity.ConversationReference`
         :return:
@@ -102,7 +102,7 @@ class ChannelAdapter(ABC, ChannelAdapterProtocol):
         :param reference: A reference to the conversation to continue.
         :type reference: :class:`microsoft_agents.activity.ConversationReference`
         :param callback: The method to call for the resulting agent turn.
-        :type callback: Callable[[TurnContext], Awaitable]
+        :type callback: Callable[[microsoft_agents.hosting.core.turn_context.TurnContext], Awaitable]
         :param claims_identity: A :class:`microsoft_agents.hosting.core.ClaimsIdentity` for the conversation.
         :type claims_identity: :class:`microsoft_agents.hosting.core.ClaimsIdentity`
         :param audience:A value signifying the recipient of the proactive message.
@@ -124,11 +124,11 @@ class ChannelAdapter(ABC, ChannelAdapterProtocol):
         to the user.
 
         :param claims_identity: A :class:`microsoft_agents.hosting.core.ClaimsIdentity` for the conversation.
-        :type claims_identity: :class:`microsoft_agents.hosting.core.ClaimsIdentity`
+        :type claims_identity: :class:`microsoft_agents.hosting.core.authorization.ClaimsIdentity`
         :param continuation_activity: The activity to send.
         :type continuation_activity: :class:`microsoft_agents.activity.Activity`
         :param callback: The method to call for the resulting agent turn.
-        :type callback: Callable[[TurnContext], Awaitable]
+        :type callback: Callable[[microsoft_agents.hosting.core.turn_context.TurnContext], Awaitable]
         :param audience: A value signifying the recipient of the proactive message.
         :type audience: str
         """
@@ -155,9 +155,9 @@ class ChannelAdapter(ABC, ChannelAdapterProtocol):
         :param audience: A value signifying the recipient of the proactive message.
         :type audience: str
         :param conversation_parameters: The information to use to create the conversation
-        :type conversation_parameters: :class:`microsoft_agents.activity.models.ConversationParameters`
+        :type conversation_parameters: :class:`microsoft_agents.activity.ConversationParameters`
         :param callback: The method to call for the resulting agent turn.
-        :type callback: Callable[[TurnContext], Awaitable]
+        :type callback: Callable[[microsoft_agents.hosting.core.turn_context.TurnContext], Awaitable]
 
         :raises: Exception - Not implemented or when the implementation fails.
 
@@ -222,7 +222,7 @@ class ChannelAdapter(ABC, ChannelAdapterProtocol):
         the end of the chain.
 
         :param context: The context object for the turn.
-        :type context: :class:`TurnContext`
+        :type context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         :param callback: A callback method to run at the end of the pipeline.
         :type callback: Callable[[TurnContext], Awaitable]
         :return:

microsoft_agents/hosting/core/connector/client/user_token_client.py

@@ -8,7 +8,12 @@ from typing import Optional
 from aiohttp import ClientSession
 
 from microsoft_agents.hosting.core.connector import UserTokenClientBase
-from microsoft_agents.activity import TokenResponse, TokenStatus, SignInResource
+from microsoft_agents.activity import (
+    TokenOrSignInResourceResponse,
+    TokenResponse,
+    TokenStatus,
+    SignInResource,
+)
 from ..get_product_info import get_product_info
 from ..user_token_base import UserTokenBase
 from ..agent_sign_in_base import AgentSignInBase
@@ -110,15 +115,6 @@ class UserToken(UserTokenBase):
         channel_id: Optional[str] = None,
         code: Optional[str] = None,
     ) -> TokenResponse:
-        """
-        Gets a token for a user and connection.
-
-        :param user_id: ID of the user.
-        :param connection_name: Name of the connection to use.
-        :param channel_id: ID of the channel.
-        :param code: Optional authorization code.
-        :return: A token response.
-        """
         params = {"userId": user_id, "connectionName": connection_name}
 
         if channel_id:
@@ -137,6 +133,40 @@ class UserToken(UserTokenBase):
             data = await response.json()
             return TokenResponse.model_validate(data)
 
+    async def _get_token_or_sign_in_resource(
+        self,
+        user_id: str,
+        connection_name: str,
+        channel_id: str,
+        state: str,
+        code: str = "",
+        final_redirect: str = "",
+        fwd_url: str = "",
+    ) -> TokenOrSignInResourceResponse:
+
+        params = {
+            "userId": user_id,
+            "connectionName": connection_name,
+            "channelId": channel_id,
+            "state": state,
+            "code": code,
+            "finalRedirect": final_redirect,
+            "fwdUrl": fwd_url,
+        }
+
+        logger.info("Getting token or sign-in resource with params: %s", params)
+        async with self.client.get(
+            "/api/usertoken/GetTokenOrSignInResource", params=params
+        ) as response:
+            if response.status != 200:
+                logger.error(
+                    "Error getting token or sign-in resource: %s", response.status
+                )
+                response.raise_for_status()
+
+            data = await response.json()
+            return TokenOrSignInResourceResponse.model_validate(data)
+
     async def get_aad_tokens(
         self,
         user_id: str,
@@ -144,15 +174,6 @@ class UserToken(UserTokenBase):
         channel_id: Optional[str] = None,
         body: Optional[dict] = None,
     ) -> dict[str, TokenResponse]:
-        """
-        Gets Azure Active Directory tokens for a user and connection.
-
-        :param user_id: ID of the user.
-        :param connection_name: Name of the connection to use.
-        :param channel_id: ID of the channel.
-        :param body: An optional dictionary containing resource URLs.
-        :return: A dictionary of tokens.
-        """
         params = {"userId": user_id, "connectionName": connection_name}
 
         if channel_id:
@@ -175,13 +196,6 @@ class UserToken(UserTokenBase):
         connection_name: Optional[str] = None,
         channel_id: Optional[str] = None,
     ) -> None:
-        """
-        Signs the user out from the specified connection.
-
-        :param user_id: ID of the user.
-        :param connection_name: Name of the connection to use.
-        :param channel_id: ID of the channel.
-        """
         params = {"userId": user_id}
 
         if connection_name:
@@ -203,14 +217,6 @@ class UserToken(UserTokenBase):
         channel_id: Optional[str] = None,
         include: Optional[str] = None,
     ) -> list[TokenStatus]:
-        """
-        Gets token status for the user.
-
-        :param user_id: ID of the user.
-        :param channel_id: ID of the channel.
-        :param include: Optional filter.
-        :return: A list of token status objects.
-        """
         params = {"userId": user_id}
 
         if channel_id:
@@ -236,15 +242,6 @@ class UserToken(UserTokenBase):
         channel_id: str,
         body: Optional[dict] = None,
     ) -> TokenResponse:
-        """
-        Exchanges a token.
-
-        :param user_id: ID of the user.
-        :param connection_name: Name of the connection to use.
-        :param channel_id: ID of the channel.
-        :param body: An optional token exchange request body.
-        :return: A token response.
-        """
         params = {
             "userId": user_id,
             "connectionName": connection_name,

microsoft_agents/hosting/core/connector/user_token_base.py

@@ -1,10 +1,19 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 from abc import abstractmethod
 from typing import Protocol
 
-from microsoft_agents.activity import TokenResponse, TokenStatus
+from microsoft_agents.activity import (
+    TokenResponse,
+    TokenStatus,
+    TokenOrSignInResourceResponse,
+)
 
 
 class UserTokenBase(Protocol):
+    """Base class for user token operations."""
+
     @abstractmethod
     async def get_token(
         self,
@@ -13,6 +22,40 @@ class UserTokenBase(Protocol):
         channel_id: str = None,
         code: str = None,
     ) -> TokenResponse:
+        """
+        Get sign-in URL.
+
+        :param state: State parameter for OAuth flow.
+        :param code_challenge: Code challenge for PKCE.
+        :param emulator_url: Emulator URL if used.
+        :param final_redirect: Final redirect URL.
+        :return: The sign-in URL.
+        """
+        raise NotImplementedError()
+
+    @abstractmethod
+    async def _get_token_or_sign_in_resource(
+        self,
+        user_id: str,
+        connection_name: str,
+        channel_id: str,
+        state: str,
+        code: str = "",
+        final_redirect: str = "",
+        fwd_url: str = "",
+    ) -> TokenOrSignInResourceResponse:
+        """
+        Gets a token or a sign-in resource for a user and connection.
+
+        :param user_id: ID of the user.
+        :param connection_name: Name of the connection to use.
+        :param channel_id: ID of the channel.
+        :param state: State parameter for OAuth flow.
+        :param code: Optional authorization code.
+        :param final_redirect: Final redirect URL.
+        :param fwd_url: Forward URL.
+        :return: A token or sign-in resource response.
+        """
         raise NotImplementedError()
 
     @abstractmethod
@@ -23,22 +66,55 @@ class UserTokenBase(Protocol):
         channel_id: str = None,
         body: dict = None,
     ) -> dict[str, TokenResponse]:
+        """
+        Gets Azure Active Directory tokens for a user and connection.
+
+        :param user_id: ID of the user.
+        :param connection_name: Name of the connection to use.
+        :param channel_id: ID of the channel.
+        :param body: An optional dictionary containing resource URLs.
+        :return: A dictionary of tokens.
+        """
         raise NotImplementedError()
 
     @abstractmethod
     async def sign_out(
         self, user_id: str, connection_name: str = None, channel_id: str = None
     ) -> None:
+        """
+        Signs the user out from the specified connection.
+
+        :param user_id: ID of the user.
+        :param connection_name: Name of the connection to use.
+        :param channel_id: ID of the channel.
+        """
         raise NotImplementedError()
 
     @abstractmethod
     async def get_token_status(
         self, user_id: str, channel_id: str = None, include: str = None
     ) -> list[TokenStatus]:
+        """
+        Gets token status for the user.
+
+        :param user_id: ID of the user.
+        :param channel_id: ID of the channel.
+        :param include: Optional filter.
+        :return: A list of token status objects.
+        """
         raise NotImplementedError()
 
     @abstractmethod
     async def exchange_token(
         self, user_id: str, connection_name: str, channel_id: str, body: dict = None
     ) -> TokenResponse:
+        """
+        Exchanges a token.
+
+        :param user_id: ID of the user.
+        :param connection_name: Name of the connection to use.
+        :param channel_id: ID of the channel.
+        :param body: An optional token exchange request body.
+        :return: A token response.
+        """
         raise NotImplementedError()

microsoft_agents/hosting/core/connector/user_token_client_base.py

@@ -1,3 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 from abc import abstractmethod
 from typing import Protocol
 

microsoft_agents/hosting/core/state/agent_state.py

@@ -68,11 +68,11 @@ class AgentState:
 
     def __init__(self, storage: Storage, context_service_key: str):
         """
-        Initializes a new instance of the :class:`AgentState` class.
+        Initializes a new instance of the :class:`microsoft_agents.hosting.core.state.agent_state.AgentState` class.
 
         :param storage: The storage layer this state management object will use to store and retrieve state
         :type storage:  :class:`microsoft_agents.hosting.core.storage.Storage`
-        :param context_service_key: The key for the state cache for this :class:`AgentState`
+        :param context_service_key: The key for the state cache for this :class:`microsoft_agents.hosting.core.state.agent_state.AgentState`
         :type context_service_key: str
 
         .. remarks::
@@ -93,19 +93,19 @@ class AgentState:
         from the turn context.
 
         :param turn_context: The context object for this turn.
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         :return: The cached agent state instance.
         """
         return turn_context.turn_state.get(self._context_service_key)
 
     def create_property(self, name: str) -> StatePropertyAccessor:
         """
-        Creates a property definition and registers it with this :class:`AgentState`.
+        Creates a property definition and registers it with this :class:`microsoft_agents.hosting.core.state.agent_state.AgentState`.
 
         :param name: The name of the property
         :type name: str
         :return: If successful, the state property accessor created
-        :rtype: :class:`StatePropertyAccessor`
+        :rtype: :class:`microsoft_agents.hosting.core.state.state_property_accessor.StatePropertyAccessor`
         """
         if not name or not name.strip():
             raise ValueError(
@@ -123,7 +123,7 @@ class AgentState:
         Reads the current state object and caches it in the context object for this turn.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         :param force: Optional, true to bypass the cache
         :type force: bool
         """
@@ -141,7 +141,7 @@ class AgentState:
         If the state has changed, it saves the state cached in the current context for this turn.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         :param force: Optional, true to save state to storage whether or not there are changes
         :type force: bool
         """
@@ -157,7 +157,7 @@ class AgentState:
         Clears any state currently stored in this state scope.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
 
         :return: None
 
@@ -174,7 +174,7 @@ class AgentState:
         Deletes any state currently stored in this state scope.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
 
         :return: None
         """
@@ -200,7 +200,7 @@ class AgentState:
         Gets the value of the specified property in the turn context.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         :param property_name: The property name
         :type property_name: str
 
@@ -235,8 +235,6 @@ class AgentState:
         """
         Deletes a property from the state cache in the turn context.
 
-        :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
         :param property_name: The name of the property to delete
         :type property_name: str
 
@@ -254,8 +252,6 @@ class AgentState:
         """
         Sets a property to the specified value in the turn context.
 
-        :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
         :param property_name: The property name
         :type property_name: str
         :param value: The value to assign to the property
@@ -272,15 +268,15 @@ class AgentState:
 
 class BotStatePropertyAccessor(StatePropertyAccessor):
     """
-    Defines methods for accessing a state property created in a :class:`AgentState` object.
+    Defines methods for accessing a state property created in a :class:`microsoft_agents.hosting.core.state.agent_state.AgentState` object.
     """
 
     def __init__(self, agent_state: AgentState, name: str):
         """
-        Initializes a new instance of the :class:`BotStatePropertyAccessor` class.
+        Initializes a new instance of the :class:`microsoft_agents.hosting.core.state.agent_state.BotStatePropertyAccessor` class.
 
         :param agent_state: The state object to access
-        :type agent_state:  :class:`AgentState`
+        :type agent_state:  :class:`microsoft_agents.hosting.core.state.agent_state.AgentState`
         :param name: The name of the state property to access
         :type name: str
 
@@ -304,7 +300,7 @@ class BotStatePropertyAccessor(StatePropertyAccessor):
         Deletes the property.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         """
         await self._agent_state.load(turn_context, False)
         self._agent_state.delete_value(self._name)
@@ -320,7 +316,7 @@ class BotStatePropertyAccessor(StatePropertyAccessor):
         Gets the property value.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         :param default_value_or_factory: Defines the default value for the property
         """
         await self._agent_state.load(turn_context, False)
@@ -355,7 +351,7 @@ class BotStatePropertyAccessor(StatePropertyAccessor):
         Sets the property value.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
 
         :param value: The value to assign to the property
         """

{microsoft_agents_hosting_core-0.4.0.dev18.dist-info → microsoft_agents_hosting_core-0.5.0.dev3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microsoft-agents-hosting-core
-Version: 0.4.0.dev18
+Version: 0.5.0.dev3
 Summary: Core library for Microsoft Agents
 Author: Microsoft Corporation
 Project-URL: Homepage, https://github.com/microsoft/Agents
@@ -8,7 +8,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.9
-Requires-Dist: microsoft-agents-activity==0.4.0.dev18
+Requires-Dist: microsoft-agents-activity==0.5.0.dev3
 Requires-Dist: pyjwt>=2.10.1
 Requires-Dist: isodate>=0.6.1
 Requires-Dist: azure-core>=1.30.0

{microsoft_agents_hosting_core-0.4.0.dev18.dist-info → microsoft_agents_hosting_core-0.5.0.dev3.dist-info}/RECORD

@@ -1,8 +1,8 @@
 microsoft_agents/hosting/core/__init__.py,sha256=EN6Et-e7n5n_nhXy5ZKNiRtjMfEgWkoNri_gk8KEYLw,4862
-microsoft_agents/hosting/core/activity_handler.py,sha256=1VmxFvRBAGL-s1X6kURIpNVemlqbB0aBzRiVnwbHhdA,26712
+microsoft_agents/hosting/core/activity_handler.py,sha256=aXNtqHuxXdkIYUylWohRZwmBd4Kw0aSc3a1PTdDdXDA,26811
 microsoft_agents/hosting/core/agent.py,sha256=K8v84y8ULP7rbcMKg8LxaM3haAq7f1oHFCLy3AAphQE,574
 microsoft_agents/hosting/core/card_factory.py,sha256=UDmPEpOk2SpEr9ShN9Q0CiaI_GTD3qjHgkDMOWinW9I,6926
-microsoft_agents/hosting/core/channel_adapter.py,sha256=zEfQILXagYujO_dTsqvTbqdegeOW4qEHP8SdJb_IPEY,10088
+microsoft_agents/hosting/core/channel_adapter.py,sha256=LVHSueET6kzv-N_OCdl3F0yL4-OvZCMKMsj5tpPzZD0,10396
 microsoft_agents/hosting/core/channel_api_handler_protocol.py,sha256=RO59hiOYx7flQVWhX6VGvfpFPoKVkdT_la-7WhUl8UM,4506
 microsoft_agents/hosting/core/channel_service_adapter.py,sha256=pLhHJ86HP_6z8V5HJW9vvE8u98MP028HOYkPmvtUESA,17263
 microsoft_agents/hosting/core/channel_service_client_factory_base.py,sha256=ArMAUt84Kzq17Oyqz6o8HZrc01UqAAmNCSBTShv3rgk,1704
@@ -11,15 +11,15 @@ microsoft_agents/hosting/core/middleware_set.py,sha256=TBsBs4KwAfKyHlQTlG4bl1y5U
 microsoft_agents/hosting/core/rest_channel_service_client_factory.py,sha256=afLeWgLz9N417Egc_6LBfnYNiuuwTEcSBefeOvTQ_H4,6217
 microsoft_agents/hosting/core/turn_context.py,sha256=df7TB1uXurgoAk338OF6taVfVgS58v662A9D9-GLP64,14794
 microsoft_agents/hosting/core/_oauth/__init__.py,sha256=sU1HsIXbETRYwnudtFc6GrNbM6C3oYjmruqXc6kIAFw,405
-microsoft_agents/hosting/core/_oauth/_flow_state.py,sha256=WgvwVbEVsVb5ax75BleCVfGDs-Zw3beDZGlzW6jraCg,2185
+microsoft_agents/hosting/core/_oauth/_flow_state.py,sha256=BQbXn0a3Fw4aozS-WSjL0Y7vEdb4eua1ZitSr0qZ6bE,2207
 microsoft_agents/hosting/core/_oauth/_flow_storage_client.py,sha256=1MLD8m_qw0jSLqsyNaaWHm7aFkdjNWOE7xhV1rfbU64,3413
-microsoft_agents/hosting/core/_oauth/_oauth_flow.py,sha256=6PGuba1xlIVZK7zhZFytwL9c7gBpNuGiIjKCUTH4cLU,12061
+microsoft_agents/hosting/core/_oauth/_oauth_flow.py,sha256=vgg_sQLYr83YA0F7aQ1K5j8vEATw7ZS151ODkpCGYAM,12211
 microsoft_agents/hosting/core/app/__init__.py,sha256=GZQdog7BBMA8uD9iaRMNeRJf12rJZB3bAKFAD8Y8dVo,1228
 microsoft_agents/hosting/core/app/_type_defs.py,sha256=b5VZFWnQ5ONUZMtFxw7Q-mbbxIUSJ7RXcCXjqdHwSQw,438
-microsoft_agents/hosting/core/app/agent_application.py,sha256=qczGDK_yTR-v3cqvJkTTfShcq-_ia6631OxljHlBjmY,30014
+microsoft_agents/hosting/core/app/agent_application.py,sha256=81oMh9En7wtuZdsP_6tj0eEu05LYDuRp9ko9TJ1x-aw,30014
 microsoft_agents/hosting/core/app/app_error.py,sha256=JgYBgv2EKe9Q2TFi5FeG_RneulBEa5SyBpWSF-duBzE,301
 microsoft_agents/hosting/core/app/app_options.py,sha256=P3XTFFuQCnEcHixfdmr5RPG-Wli4c1VSmCMRKVBBLsw,2792
-microsoft_agents/hosting/core/app/input_file.py,sha256=wAnAwKqC0SKyRQ9sOoIly04C-GFkAFN-w-yoJkCjWc8,1151
+microsoft_agents/hosting/core/app/input_file.py,sha256=AEzVAnAPO1V7MWDI_uoZfcYY8Oog3XgvEpAeO-tATeY,1546
 microsoft_agents/hosting/core/app/query.py,sha256=lToDWFG7exUyPC5zxvna89013fDPKrUGOI8jyWFoUYk,328
 microsoft_agents/hosting/core/app/typing_indicator.py,sha256=CxLtgDTr6a8ELqUujHMvAh_CYpm3mwhomH-tfTQGSe8,1558
 microsoft_agents/hosting/core/app/_routes/__init__.py,sha256=faz05Hk5Z1IGIXUwXljohym0lzE8nW3CbTpXlE-VcB0,300
@@ -30,11 +30,11 @@ microsoft_agents/hosting/core/app/oauth/__init__.py,sha256=eHx-vmW2Ew8HULSfvAmV8
 microsoft_agents/hosting/core/app/oauth/_sign_in_response.py,sha256=H5VBX69WiYXGALzCDVnF_-Y0brbafbJgfF4mS2wZSr0,851
 microsoft_agents/hosting/core/app/oauth/_sign_in_state.py,sha256=lC2otIFcQthAZ8kqkYxV3wLBPOqzW9MRVUbdqQPtEdM,1159
 microsoft_agents/hosting/core/app/oauth/auth_handler.py,sha256=KyhEfpKtoVKcapOt4szpDdbgk_KSwXF46GGOeJrmsRI,3464
-microsoft_agents/hosting/core/app/oauth/authorization.py,sha256=a5XQtY8E7ZKbfqht3TxqTg0z4t-8cV8Bx8VoPft5v28,16115
+microsoft_agents/hosting/core/app/oauth/authorization.py,sha256=TFKibquBybHbCnmnmcMYkL79CQrcOZrpaci26MtseoI,16115
 microsoft_agents/hosting/core/app/oauth/_handlers/__init__.py,sha256=ZQuXF-IZrJv_hOgt-sdRFAUyIpRXaYqYBuyEJWJRcfU,376
-microsoft_agents/hosting/core/app/oauth/_handlers/_authorization_handler.py,sha256=YpVNA6X47wX58EGmCXXEyCGpUN7KtCDN7p7j64WUyiA,4185
-microsoft_agents/hosting/core/app/oauth/_handlers/_user_authorization.py,sha256=6hzhnvLxfcXrFMOToxq8iFz0urS0H8ChD5mD3PrV0Pk,10186
-microsoft_agents/hosting/core/app/oauth/_handlers/agentic_user_authorization.py,sha256=XynKtw2lnhNz1QjQuxOhg_EIEgjLRoIJPipAD3-yE4I,7145
+microsoft_agents/hosting/core/app/oauth/_handlers/_authorization_handler.py,sha256=W36Y1m0zFaRmdt-cL3ZKoHxx95y0O7YJF9D0cXx_s24,4185
+microsoft_agents/hosting/core/app/oauth/_handlers/_user_authorization.py,sha256=o_pn5ZO7O-YvcC5NGlUgcCmVLD-f6KwQ5CRIsPp8zQE,10186
+microsoft_agents/hosting/core/app/oauth/_handlers/agentic_user_authorization.py,sha256=7rGzYRLOzcy9vGAwnzjyImEaCy0G_bRUwufuXp3xiwk,7145
 microsoft_agents/hosting/core/app/state/__init__.py,sha256=aL_8GB7_de8LUSEOgTJQFRx1kvgvJHHJVv7nWAoRPmU,331
 microsoft_agents/hosting/core/app/state/conversation_state.py,sha256=LfcSwvhaU0JeAahwg9YA9uz0kKHa9c6Y3XBAWqwuMg0,1593
 microsoft_agents/hosting/core/app/state/state.py,sha256=-2vN8MIYs4d2PAEGGlxV-dgBRZG0BT_eHfgvt59zyow,5353
@@ -69,15 +69,15 @@ microsoft_agents/hosting/core/connector/attachments_base.py,sha256=eqr5dbrc7oE77
 microsoft_agents/hosting/core/connector/connector_client_base.py,sha256=DKog6C1Z8V9r_Lp-IvXUiAbJN_iJMFary5FvejjHlaw,583
 microsoft_agents/hosting/core/connector/conversations_base.py,sha256=fM5PCDaSkxMPatNo4WTcbjxLfrHydd51WX9_2_2F-DM,3754
 microsoft_agents/hosting/core/connector/get_product_info.py,sha256=SDxPqBCzzQLEUsaZ4S9lB95ibo9LMGd1-K5Uf7vcAwo,962
-microsoft_agents/hosting/core/connector/user_token_base.py,sha256=kEJxGMMl-RYzqDKqjwjQPvc-acih0cJo3hOEjmmom5I,1195
-microsoft_agents/hosting/core/connector/user_token_client_base.py,sha256=JTkbG70YXEnAQA_2yJn9dUGQ-hSCwNgU0C-V8y7kGEI,376
+microsoft_agents/hosting/core/connector/user_token_base.py,sha256=h_l5D1SghN2RrUkFcKWQhCHlO9r7akMbzsm2x8MvomI,3639
+microsoft_agents/hosting/core/connector/user_token_client_base.py,sha256=dfUTUsBNOzWze9_JldAeLe73sydSDzlKyMKMvj48g2E,471
 microsoft_agents/hosting/core/connector/client/__init__.py,sha256=6JdKhmm7btmo0omxMBd8PJbtGFk0cnMwVUoStyW7Ft0,143
 microsoft_agents/hosting/core/connector/client/connector_client.py,sha256=UsvQrWROhrFQxyBu6TY9ej3wUS__VpcdpNZG8fu4-Tc,23398
-microsoft_agents/hosting/core/connector/client/user_token_client.py,sha256=a6Y4pD8Ae-pEFA8FrXgb_mb0TzWjo81TMeDaRPqcGIw,10896
+microsoft_agents/hosting/core/connector/client/user_token_client.py,sha256=1ey1mqV7pkC94Xl36PVrx5TOyumJQbpscbm2W9uvpHs,10609
 microsoft_agents/hosting/core/connector/teams/__init__.py,sha256=3ZMPGYyZ15EwvfQzfJJQy1J58oIt4InSxibl3BN6R54,100
 microsoft_agents/hosting/core/connector/teams/teams_connector_client.py,sha256=XGQDTYHrA_I9n9JlxGST5eesjsFhz2dnSaMSuyoFnKU,12676
 microsoft_agents/hosting/core/state/__init__.py,sha256=yckKi1wg_86ng-DL9Q3R49QiWKvNjPkVNk6HClWgVrY,208
-microsoft_agents/hosting/core/state/agent_state.py,sha256=p6AoKSPNpPR6Ubw_APjrQ_KyaQ9AqRYS63n4HcmMnzs,13211
+microsoft_agents/hosting/core/state/agent_state.py,sha256=uboptWaC3VrSGTnXIzaO38XUqOT-ITW6EhJxuGMtKWs,13724
 microsoft_agents/hosting/core/state/state_property_accessor.py,sha256=kpiNnzkZ6el-oRITRbRkk1Faa_CPFxpJQdvSGxIJP70,1392
 microsoft_agents/hosting/core/state/user_state.py,sha256=zEigX-sroNAyoQAxQjG1OgmJQKjk1zOkdeqylFg7M2E,1484
 microsoft_agents/hosting/core/storage/__init__.py,sha256=Df_clI0uMRgcr4Td-xkP83bU_mGae7_gRMhtVDPZDmE,729
@@ -91,7 +91,7 @@ microsoft_agents/hosting/core/storage/transcript_info.py,sha256=5VN32j99tshChAff
 microsoft_agents/hosting/core/storage/transcript_logger.py,sha256=_atDk3CJ05fIVMhlWGNa91IiM9bGLmOhasFko8Lxjhk,8237
 microsoft_agents/hosting/core/storage/transcript_memory_store.py,sha256=v1Ud9LSs8m5c9_Fa8i49SuAjw80dX1hDciqbRduDEOE,6444
 microsoft_agents/hosting/core/storage/transcript_store.py,sha256=ka74o0WvI5GhMZcFqSxVdamBhGzZcDZe6VNkG-sMy74,1944
-microsoft_agents_hosting_core-0.4.0.dev18.dist-info/METADATA,sha256=Sn6wAcHWeWywoOH8JkbMTpZVkpNTVLl6rskzOoxBc-4,586
-microsoft_agents_hosting_core-0.4.0.dev18.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-microsoft_agents_hosting_core-0.4.0.dev18.dist-info/top_level.txt,sha256=lWKcT4v6fTA_NgsuHdNvuMjSrkiBMXohn64ApY7Xi8A,17
-microsoft_agents_hosting_core-0.4.0.dev18.dist-info/RECORD,,
+microsoft_agents_hosting_core-0.5.0.dev3.dist-info/METADATA,sha256=TyD_JZidNIMbh1vaGa7POTFfFSsDOnAxAEaHxgKZhZc,584
+microsoft_agents_hosting_core-0.5.0.dev3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+microsoft_agents_hosting_core-0.5.0.dev3.dist-info/top_level.txt,sha256=lWKcT4v6fTA_NgsuHdNvuMjSrkiBMXohn64ApY7Xi8A,17
+microsoft_agents_hosting_core-0.5.0.dev3.dist-info/RECORD,,