Update WorkflowContext to use Never as default type parameter instead of None

[Copilot]

This PR updates the WorkflowContext class to use Never as the default value for its type parameter instead of None, aligning with Python typing best practices and making the intent clearer for type checkers.

Changes Made

Core Type System Updates

• Updated T_Out = TypeVar("T_Out") to T_Out = TypeVar("T_Out", default=Never) in _workflow_context.py
• Added necessary imports: from typing import Never and from typing_extensions import TypeVar
• Updated all internal framework code to use WorkflowContext[Never] instead of WorkflowContext[None]

Validation and Error Messages

• All validation error messages now suggest WorkflowContext[Never] instead of WorkflowContext[None]
• Added validation support for Never type while maintaining backward compatibility with None
• Updated docstrings and comments to reference Never instead of None

Function Executor Support

• Updated type inference logic to handle Never alongside existing None support
• Both WorkflowContext[Never] and WorkflowContext[None] now correctly infer empty output types ([])

Example Usage

Before (still supported for backward compatibility):

class MyExecutor(Executor):
    @handler
    async def handle(self, message: str, ctx: WorkflowContext[None]) -> None:
        # Handler that doesn't emit messages
        pass

After (recommended approach):

class MyExecutor(Executor):
    @handler
    async def handle(self, message: str, ctx: WorkflowContext[Never]) -> None:
        # Handler that doesn't emit messages
        pass

Why Never Instead of None?

In Python's type system, Never (or NoReturn) is the appropriate type for contexts that never produce/emit values, while None represents the absence of a value. Using Never makes the intent clearer:

• Never semantically indicates "this context will never emit messages"
• Type checkers can better understand and validate the code
• It follows Python typing conventions for similar scenarios

Backward Compatibility

This change maintains full backward compatibility:

• Existing code using WorkflowContext[None] continues to work without modification
• All existing tests pass
• The framework accepts both Never and None type parameters
• Only error messages and recommendations have been updated to suggest the new approach

Testing

• Added comprehensive tests for WorkflowContext[Never] validation
• Added tests for Never output type inference in function executors
• Added test to verify the TypeVar default is Never
• Updated validation tests to expect Never in error messages
• All existing tests (40+ validation tests) continue to pass

This pull request was created as a result of the following prompt from Copilot chat.

Update the WorkflowContext class to use Never as the default value for its type parameter instead of None. This change should be implemented in the microsoft/agent-framework repository. Ensure that all relevant documentation and usages of WorkflowContext are updated accordingly to reflect this change. Additionally, verify and update any existing type checks or constraints that depend on the default value of the type parameter.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[ekzhu]

Don't target main branch target ekzhu/workflow-output branch @copilot