@microsoft/agents-hosting 1.1.0-alpha.2 → 1.1.0-alpha.58

package/src/app/auth/types.ts

@@ -0,0 +1,111 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Activity } from '@microsoft/agents-activity'
+import { Storage, StoreItem } from '../../storage'
+import { TurnContext } from '../../turnContext'
+import { AgenticAuthorizationOptions, AzureBotAuthorizationOptions } from './handlers'
+import { TokenResponse } from '../../oauth'
+import { Connections } from '../../auth/connections'
+
+/**
+ * Authorization configuration options.
+ */
+export type AuthorizationOptions = Record<string, AzureBotAuthorizationOptions | AgenticAuthorizationOptions>
+
+/**
+ * Represents the status of a handler registration attempt.
+ */
+export enum AuthorizationHandlerStatus {
+  /** The handler has approved the request - validation passed */
+  APPROVED = 'approved',
+  /** The handler registration is pending further action */
+  PENDING = 'pending',
+  /** The handler has rejected the request - validation failed */
+  REJECTED = 'rejected',
+  /** The handler has ignored the request - no action taken */
+  IGNORED = 'ignored',
+  /** The handler requires revalidation */
+  REVALIDATE = 'revalidate'
+}
+
+/**
+ * Active handler manager information.
+ */
+export interface ActiveAuthorizationHandler extends StoreItem {
+  /**
+   * Unique identifier for the handler.
+   */
+  readonly id: string
+  /**
+   * The current activity associated with the handler.
+   */
+  activity: Activity
+}
+
+export interface AuthorizationHandler {
+  /**
+   * Unique identifier for the handler.
+   */
+  readonly id: string
+  /**
+   * Initiates the sign-in process for the handler.
+   * @param context The turn context.
+   * @param active Optional active handler data.
+   * @returns The status of the sign-in attempt.
+   */
+  signin(context: TurnContext, active?: ActiveAuthorizationHandler): Promise<AuthorizationHandlerStatus>
+  /**
+   * Initiates the sign-out process for the handler.
+   * @param context The turn context.
+   * @returns A promise that resolves to a boolean indicating the success of the sign-out attempt.
+   */
+  signout(context: TurnContext): Promise<boolean>;
+  /**
+   * Retrieves an access token for the specified scopes.
+   * @param context The turn context.
+   * @param options Optional token request options.
+   * @returns The access token response.
+   */
+  token(context: TurnContext, options?: AuthorizationHandlerTokenOptions): Promise<TokenResponse>;
+  /**
+   * Registers a callback to be invoked when the sign-in process is successful.
+   * @param callback The callback to invoke on success.
+   */
+  onSuccess(callback: (context: TurnContext) => Promise<void> | void): void;
+  /**
+   * Registers a callback to be invoked when the sign-in process fails.
+   * @param callback The callback to invoke on failure.
+   */
+  onFailure(callback: (context: TurnContext, reason?: string) => Promise<void> | void): void;
+}
+
+/**
+ * Common settings required by authorization handlers.
+ */
+export interface AuthorizationHandlerSettings {
+  /**
+   * Storage instance for persisting handler state.
+   */
+  storage: Storage
+  /**
+   * Connections instance for managing authentication connections.
+   */
+  connections: Connections
+}
+
+/**
+ * Options for token requests in authorization handlers.
+ */
+export interface AuthorizationHandlerTokenOptions {
+  /**
+   * Optional name of the connection to use for the token request. Usually used for OBO flows.
+   */
+  connection?: string
+  /**
+   * Optional scopes to request in the token. Usually used for OBO flows.
+   */
+  scopes?: string[]
+}

package/src/app/index.ts

@@ -2,13 +2,12 @@ export * from './agentApplication'
 export * from './agentApplicationBuilder'
 export * from './agentApplicationOptions'
 export * from './appRoute'
-export * from './attachmentDownloader'
-export * from './authorization'
-export * from './conversationUpdateEvents'
 export * from './routeHandler'
 export * from './routeList'
 export * from './routeRank'
 export * from './routeSelector'
+export * from './attachmentDownloader'
+export * from './conversationUpdateEvents'
 export * from './turnState'
 export * from './turnEvents'
 export * from './turnStateEntry'

package/src/app/inputFileDownloader.ts

@@ -31,11 +31,19 @@ export interface InputFile {
  */
 export interface InputFileDownloader<TState extends TurnState = TurnState> {
   /**
-   * Downloads files based on the provided turn context and state.
+   * Downloads files based on the provided turn context.
    *
    * @param context - The turn context for the current operation.
-   * @param state - The state associated with the current turn.
    * @returns A promise that resolves to an array of input files.
    */
-  downloadFiles(context: TurnContext, state: TState): Promise<InputFile[]>;
+  downloadFiles(context: TurnContext): Promise<InputFile[]>;
+
+  /**
+   * Downloads files based on the provided turn context and store them in the provided state.
+   *
+   * @param context - The turn context for the current operation.
+   * @param state - The state associated with the current turn.
+   * @returns A promise that resolves once the files have been saved into state (void).
+   */
+  downloadAndStoreFiles(context: TurnContext, state: TState): Promise<void>;
 }

package/src/app/routeList.ts

@@ -17,17 +17,36 @@ export class RouteList<TState extends TurnState> {
     handler: RouteHandler<TState>,
     isInvokeRoute: boolean = false,
     rank: number = RouteRank.Unspecified,
-    authHandlers: string[] = []
+    authHandlers: string[] = [],
+    isAgenticRoute: boolean = false
   ): this {
-    this._routes.push({ selector, handler, isInvokeRoute, rank, authHandlers })
+    this._routes.push({ selector, handler, isInvokeRoute, rank, authHandlers, isAgenticRoute })
 
-    // Invoke selectors are first, then order by rank ascending
+    // Ordered by:
+    //    Agentic + Invoke
+    //    Invoke
+    //    Agentic
+    //    Other
+    // Then by Rank
     this._routes.sort((a, b) => {
-      if (a.isInvokeRoute !== b.isInvokeRoute) {
-        return a.isInvokeRoute ? -1 : 1
+      const getPriority = (route: AppRoute<TState>) => {
+        if (route.isAgenticRoute && route.isInvokeRoute) return 0
+        if (route.isInvokeRoute) return 1
+        if (route.isAgenticRoute) return 2
+        return 3
       }
+
+      const priorityA = getPriority(a)
+      const priorityB = getPriority(b)
+
+      if (priorityA !== priorityB) {
+        return priorityA - priorityB
+      }
+
+      // If priorities are equal, sort by rank
       return (a.rank ?? 0) - (b.rank ?? 0)
     })
+
     return this
   }
 

package/src/app/streaming/streamingResponse.ts

@@ -29,6 +29,7 @@ export class StreamingResponse {
   private _message: string = ''
   private _attachments?: Attachment[]
   private _ended = false
+  private _delayInMs = 1500
 
   // Queue for outgoing activities
   private _queue: Array<() => Activity> = []
@@ -80,6 +81,13 @@ export class StreamingResponse {
     return this._nextSequence - 1
   }
 
+  /**
+   * Gets the delay in milliseconds between chunks.
+   */
+  public get delayInMs (): number {
+    return this._delayInMs
+  }
+
   /**
      * Queues an informative update to be sent to the client.
      *
@@ -183,7 +191,8 @@ export class StreamingResponse {
           appearance: {
             '@type': 'DigitalDocument',
             name: citation.title || `Document #${currPos + 1}`,
-            abstract: CitationUtil.snippet(citation.content, 477)
+            abstract: CitationUtil.snippet(citation.content, 477),
+            url: citation.url!
           }
         }
         currPos++
@@ -222,6 +231,14 @@ export class StreamingResponse {
     this._enableGeneratedByAILabel = enableGeneratedByAILabel
   }
 
+  /**
+   * Sets the delay in milliseconds between chunks.
+   * @param delayInMs The delay in milliseconds.
+   */
+  public setDelayInMs (delayInMs: number): void {
+    this._delayInMs = delayInMs
+  }
+
   /**
      * Returns the most recently streamed message.
      *
@@ -236,7 +253,7 @@ export class StreamingResponse {
      *
      * @returns {Promise<void>} - A promise representing the async operation.
      */
-  public waitForQueue (): Promise<void> {
+  private waitForQueue (): Promise<void> {
     return this._queueSync || Promise.resolve()
   }
 
@@ -370,7 +387,7 @@ export class StreamingResponse {
 
     // Send activity
     const response = await this._context.sendActivity(activity)
-    await new Promise((resolve) => setTimeout(resolve, 1500))
+    await new Promise((resolve) => setTimeout(resolve, this.delayInMs))
 
     // Save assigned stream ID
     if (!this._streamId) {

package/src/app/turnState.ts

@@ -5,7 +5,6 @@
 
 import { Storage, StoreItems } from '../storage'
 import { AppMemory } from './appMemory'
-import { InputFile } from './inputFileDownloader'
 import { TurnStateEntry } from './turnStateEntry'
 import { TurnContext } from '../turnContext'
 import { debug } from '@microsoft/agents-activity/logger'
@@ -30,22 +29,11 @@ export interface DefaultConversationState {}
  */
 export interface DefaultUserState {}
 
-/**
- * Default interface for temporary state that persists only during the current turn.
- * Contains properties used for handling user input, file attachments, and OAuth flows.
- */
-export interface DefaultTempState {
-  /** Collection of files attached to the current message */
-  inputFiles: InputFile[];
-}
-
 /**
  * Base class defining a collection of turn state scopes.
  *
  * @typeParam TConversationState - Type for conversation-scoped state
  * @typeParam TUserState - Type for user-scoped state
- * @typeParam TTempState - Type for temporary state that exists only for the current turn
- * @typeParam TSSOState - Type for Single Sign-On (SSO) state
  *
  * @remarks
  * Developers can create a derived class that extends `TurnState` to add additional state scopes.
@@ -80,8 +68,7 @@ export interface DefaultTempState {
  */
 export class TurnState<
     TConversationState = DefaultConversationState,
-    TUserState = DefaultUserState,
-    TTempState = DefaultTempState
+    TUserState = DefaultUserState
 > implements AppMemory {
   private _scopes: Record<string, TurnStateEntry> = {}
   private _isLoaded = false
@@ -128,37 +115,6 @@ export class TurnState<
     return this._isLoaded
   }
 
-  /**
-   * Gets the temporary state for the current turn.
-   *
-   * @returns The temporary state object
-   * @throws Error if state hasn't been loaded
-   *
-   * @remarks
-   * This state is not persisted between turns.
-   */
-  public get temp (): TTempState {
-    const scope = this.getScope(TEMP_SCOPE)
-    if (!scope) {
-      throw new Error(this._stateNotLoadedString)
-    }
-    return scope.value as TTempState
-  }
-
-  /**
-   * Sets the temporary state for the current turn.
-   *
-   * @param value - The new temporary state object
-   * @throws Error if state hasn't been loaded
-   */
-  public set temp (value: TTempState) {
-    const scope = this.getScope(TEMP_SCOPE)
-    if (!scope) {
-      throw new Error(this._stateNotLoadedString)
-    }
-    scope.replace(value as Record<string, unknown>)
-  }
-
   /**
    * Gets the user-scoped state.
    *
@@ -206,22 +162,6 @@ export class TurnState<
     scope.delete()
   }
 
-  /**
-   * Marks the temporary state for deletion.
-   *
-   * @throws Error if state hasn't been loaded
-   *
-   * @remarks
-   * Since temporary state is not persisted, this just clears the in-memory object.
-   */
-  public deleteTempState (): void {
-    const scope = this.getScope(TEMP_SCOPE)
-    if (!scope) {
-      throw new Error(this._stateNotLoadedString)
-    }
-    scope.delete()
-  }
-
   /**
    * Marks the user state for deletion.
    *
@@ -255,6 +195,7 @@ export class TurnState<
    *
    * @remarks
    * Format: "scope.property" or just "property" (defaults to temp scope)
+   * The temp scope is internal-only, not persisted to storage, and exists only for the current turn.
    */
   public deleteValue (path: string): void {
     const { scope, name } = this.getScopeAndName(path)

package/src/auth/MemoryCache.ts

@@ -0,0 +1,59 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+const CACHE_PURGE_INTERVAL = 60000 // 60 seconds
+
+/**
+ * Simple in-memory cache with TTL support.
+ * This is used to store authentication tokens for Agentic Identity scenarios only!
+ */
+export class MemoryCache<T> {
+  private cache = new Map<string, { value: T; validUntil: number }>()
+  private purgeInterval?: NodeJS.Timeout
+
+  /**
+   * Clears the purge interval to allow the process to exit cleanly
+   */
+  destroy (): void {
+    if (this.purgeInterval) {
+      clearInterval(this.purgeInterval)
+      this.purgeInterval = undefined
+    }
+  }
+
+  set (key: string, value: T, ttlSeconds: number): void {
+    const validUntil = Date.now() + (ttlSeconds * 1000)
+    this.cache.set(key, { value, validUntil })
+    if (!this.purgeInterval) {
+      this.purgeInterval = setInterval(() => this.purge(), CACHE_PURGE_INTERVAL)
+    }
+  }
+
+  get (key: string): T | undefined {
+    const item = this.cache.get(key)
+    if (!item) {
+      return undefined
+    }
+
+    // Check if item has expired
+    if (Date.now() > item.validUntil) {
+      this.cache.delete(key)
+      return undefined
+    }
+    return item.value
+  }
+
+  delete (key: string): boolean {
+    return this.cache.delete(key)
+  }
+
+  purge (): void {
+    const now = Date.now()
+    for (const [key, { validUntil }] of this.cache.entries()) {
+      if (now > validUntil) {
+        this.cache.delete(key)
+      }
+    }
+  }
+}