Merge branch 'main' into users/johanb/CodeReviewSkill

Author: pontemonti

CLAUDE.md

@@ -168,11 +168,45 @@ Place it before imports with one blank line after.
 
 ### Python Conventions
 
-- Type hints preferred (Pydantic models heavily used)
+- Type hints required on all function parameters and return types
 - Async/await patterns for I/O operations
 - Use explicit `None` checks: `if x is not None:` not `if x:`
 - Local imports should be moved to top of file
 - Return defensive copies of mutable data to protect singletons
+- **Async method naming**: Do NOT use `_async` suffix on async methods. The `_async` suffix is only appropriate when providing both sync and async versions of the same method. Since this SDK is async-only, use plain method names (e.g., `send_chat_history_messages` not `send_chat_history_messages_async`)
+
+### Type Hints - NEVER Use `Any`
+
+**CRITICAL: Never use `typing.Any` in this codebase.** Using `Any` defeats the purpose of type checking and can hide bugs. Instead:
+
+1. **Use actual types from external SDKs** - When integrating with external libraries (OpenAI, LangChain, etc.), import and use their actual types:
+   ```python
+   from agents.memory import Session
+   from agents.items import TResponseInputItem
+
+   async def send_chat_history(self, session: Session) -> OperationResult:
+       ...
+   ```
+
+2. **Use `Union` for known possible types**:
+   ```python
+   from typing import Union
+   MessageType = Union[UserMessage, AssistantMessage, SystemMessage, Dict[str, object]]
+   ```
+
+3. **Use `object` for truly unknown types** that you only pass through:
+   ```python
+   def log_item(item: object) -> None: ...
+   ```
+
+4. **Use `Protocol` only as a last resort** - If external types cannot be found or imported, define a Protocol. However, **confirm with the developer first** before proceeding with this approach, as it may indicate a missing dependency or incorrect understanding of the external API.
+
+**Why this matters:**
+- `Any` disables all type checking for that variable
+- Bugs that type checkers would catch go unnoticed
+- Code readability suffers - developers don't know what types to expect
+- Using actual SDK types provides better IDE support and ensures compatibility
+- This applies to both production code AND test files
 
 ## CI/CD
 

docs/design.md

@@ -227,9 +227,51 @@ Framework-specific adapters for MCP tool integration:
 |---------|---------|------------|
 | `extensions-agentframework` | Adapt MCP tools to Microsoft Agents SDK | [design.md](../libraries/microsoft-agents-a365-tooling-extensions-agentframework/docs/design.md) |
 | `extensions-azureaifoundry` | Azure AI Foundry tool integration | [design.md](../libraries/microsoft-agents-a365-tooling-extensions-azureaifoundry/docs/design.md) |
-| `extensions-openai` | OpenAI function calling integration | [design.md](../libraries/microsoft-agents-a365-tooling-extensions-openai/docs/design.md) |
+| `extensions-openai` | OpenAI function calling integration and chat history | [design.md](../libraries/microsoft-agents-a365-tooling-extensions-openai/docs/design.md) |
 | `extensions-semantickernel` | Semantic Kernel plugin integration | [design.md](../libraries/microsoft-agents-a365-tooling-extensions-semantickernel/docs/design.md) |
 
+#### OpenAI Extension: Chat History API
+
+The OpenAI tooling extension provides methods to send chat history to the MCP platform for real-time threat protection:
+
+**Key Classes:**
+
+| Class | Purpose |
+|-------|---------|
+| `McpToolRegistrationService` | MCP tool registration and chat history management |
+
+**Methods:**
+
+| Method | Purpose |
+|--------|---------|
+| `send_chat_history(turn_context, session, limit, options)` | Extract messages from OpenAI Session and send to MCP platform |
+| `send_chat_history_messages(turn_context, messages, options)` | Send a list of OpenAI TResponseInputItem messages to MCP platform |
+
+**Usage Example:**
+
+```python
+from agents import Agent, Runner
+from microsoft_agents_a365.tooling.extensions.openai import McpToolRegistrationService
+
+service = McpToolRegistrationService()
+agent = Agent(name="my-agent", model="gpt-4")
+
+# In your agent handler:
+async with Runner.run(agent, messages) as result:
+    session = result.session
+
+    # Option 1: Send from Session object
+    op_result = await service.send_chat_history(turn_context, session)
+
+    # Option 2: Send from message list
+    op_result = await service.send_chat_history_messages(turn_context, messages)
+
+    if op_result.succeeded:
+        print("Chat history sent successfully")
+```
+
+The methods convert OpenAI message types to `ChatHistoryMessage` format and delegate to the core `McpToolServerConfigurationService.send_chat_history()` method.
+
 ### 6. Notifications (`microsoft-agents-a365-notifications`)
 
 > **Detailed documentation**: [libraries/microsoft-agents-a365-notifications/docs/design.md](../libraries/microsoft-agents-a365-notifications/docs/design.md)

libraries/microsoft-agents-a365-tooling-extensions-agentframework/docs/design.md

@@ -76,6 +76,87 @@ mcp_tool = MCPStreamableHTTPTool(
 )
 ```
 
+### Chat History API
+
+The service provides methods to send chat history to the MCP platform for real-time threat protection analysis. This enables security scanning of conversation content.
+
+#### send_chat_history_messages
+
+The primary method for sending chat history. Converts Agent Framework `ChatMessage` objects to the `ChatHistoryMessage` format expected by the MCP platform.
+
+```python
+from agent_framework import ChatMessage, Role
+
+service = McpToolRegistrationService()
+
+# Create messages
+messages = [
+    ChatMessage(role=Role.USER, text="Hello, how are you?"),
+    ChatMessage(role=Role.ASSISTANT, text="I'm doing well, thank you!"),
+]
+
+# Send to MCP platform for threat protection
+result = await service.send_chat_history_messages(messages, turn_context)
+
+if result.succeeded:
+    print("Chat history sent successfully")
+else:
+    print(f"Failed: {result.errors}")
+```
+
+#### send_chat_history_from_store
+
+A convenience method that extracts messages from a `ChatMessageStoreProtocol` and delegates to `send_chat_history_messages`.
+
+```python
+# Using a ChatMessageStore directly
+result = await service.send_chat_history_from_store(
+    thread.chat_message_store,
+    turn_context
+)
+```
+
+#### Chat History API Parameters
+
+| Method | Parameter | Type | Description |
+|--------|-----------|------|-------------|
+| `send_chat_history_messages` | `chat_messages` | `Sequence[ChatMessage]` | Messages to send |
+| | `turn_context` | `TurnContext` | Conversation context |
+| | `tool_options` | `ToolOptions \| None` | Optional configuration |
+| `send_chat_history_from_store` | `chat_message_store` | `ChatMessageStoreProtocol` | Message store |
+| | `turn_context` | `TurnContext` | Conversation context |
+| | `tool_options` | `ToolOptions \| None` | Optional configuration |
+
+#### Chat History Integration Flow
+
+```
+Agent Framework ChatMessage objects
+       │
+       ▼
+McpToolRegistrationService.send_chat_history_messages()
+       │
+       ├── Convert ChatMessage → ChatHistoryMessage
+       │   ├── Extract role via .value property
+       │   ├── Generate UUID if message_id is None
+       │   ├── Filter out empty/whitespace content
+       │   └── Filter out None roles
+       │
+       ▼
+McpToolServerConfigurationService.send_chat_history()
+       │
+       ▼
+MCP Platform Real-Time Threat Protection Endpoint
+```
+
+#### Message Filtering Behavior
+
+The conversion process filters out invalid messages:
+- Messages with `None` role are skipped (logged at WARNING level)
+- Messages with empty or whitespace-only content are skipped
+- If all messages are filtered out, the method returns success without calling the backend
+
+This ensures only valid, meaningful messages are sent for threat analysis.
+
 ## File Structure
 
 ```