Fix AgentNotification docs broken type links and lifecycle routing bug

[Copilot]

Sphinx was expanding the AgentHandler type alias inline during doc generation, producing unresolvable strings like Callable[[Callable[[~TContext, ~TState, ... because the alias used unbound TypeVars. This broke all cross-reference links on the AgentNotification API page.

Separately, four lifecycle convenience methods (on_lifecycle, on_user_created, on_user_workload_onboarding, on_user_deleted) called self.on_lifecycle_notification(...) which does not exist, causing AttributeError at runtime.

Changes

agent_notification.py

• Removed TContext/TState TypeVars; replaced AgentHandler with a TypeAlias using concrete TurnContext, TurnState, AgentNotificationActivity — Sphinx now emits hyperlinked type names instead of ~TContext/~TState
• Added RouteHandler: TypeAlias = Callable[[TurnContext, TurnState], Awaitable[None]] to name the inner handler type
• Simplified all 8 method return type annotations from the verbose inline form to Callable[[AgentHandler], RouteHandler]
• Fixed the four lifecycle convenience methods to call self.on_agent_lifecycle_notification(...) (the method that actually exists)

# Before — TypeVars caused unresolvable doc links and wrong method call
AgentHandler = Callable[[TContext, TState, AgentNotificationActivity], Awaitable[None]]

def on_lifecycle(self, **kwargs) -> Callable[[AgentHandler], Callable[[TurnContext, TurnState], Awaitable[None]]]:
    return self.on_lifecycle_notification("*", **kwargs)   # AttributeError

# After — concrete alias, clean return type, correct dispatch
AgentHandler: TypeAlias = Callable[[TurnContext, TurnState, AgentNotificationActivity], Awaitable[None]]
RouteHandler: TypeAlias = Callable[[TurnContext, TurnState], Awaitable[None]]

def on_lifecycle(self, **kwargs) -> Callable[[AgentHandler], RouteHandler]:
    return self.on_agent_lifecycle_notification("*", **kwargs)

notifications/__init__.py

• Exports RouteHandler so callers can use it in their own type annotations.

tests/notifications/test_agent_notification.py (new)

• 16 unit tests covering type alias integrity, add_route registration for all 8 decorators, and route selector matching for subchannel and lifecycle routing.

[github-actions]

⚠️ Deprecation Warning: The deny-licenses option is deprecated for possible removal in the next major release. For more information, see issue 997.

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[JimDaly]

I expect a higher level approval is required for this to be merged.

[Copilot]

Pull request overview

Fixes AgentNotification documentation typing so Sphinx generates resolvable cross-reference links, and fixes lifecycle decorator routing so convenience APIs don’t crash at runtime.

Changes:

• Replace TypeVar-based AgentHandler with concrete TypeAlias definitions (and add RouteHandler) to improve Sphinx output.
• Fix lifecycle convenience decorators to call the correct underlying registration method (on_agent_lifecycle_notification).
• Add unit tests for type alias importability and decorator/selector behavior.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

File	Description
tests/notifications/test_agent_notification.py	Adds unit tests for public type aliases and route registration/selector behavior.
tests/notifications/init.py	Adds required license header for the new test package.
libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/agent_notification.py	Updates public type aliases for docs and fixes lifecycle convenience methods dispatch.
libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/init.py	Exports the new RouteHandler type alias.

[Copilot]

on_user_deleted() is intended to route only deletion events, but on_agent_lifecycle_notification’s selector currently returns True for any known lifecycle event when a specific event is provided. This will cause deletion handlers to run for other lifecycle events; fix the selector to check equality between requested lifecycle_event and received activity.value_type (after normalization).

[Copilot]

Lifecycle route selector tests only assert positive matches (e.g., on_user_created matches USERCREATED) but don’t assert that the selector rejects other lifecycle event types. Add negative tests (and coverage for on_user_workload_onboarding/on_user_deleted selectors) to ensure the requested lifecycle event is actually used for filtering.

[Copilot]

typing.TypeVar is a factory function, not a type, so isinstance(AgentHandler, typing.TypeVar) will raise TypeError and fail the test. If you want to assert the alias isn’t a TypeVar instance, compare against type(typing.TypeVar("T")) (or use a more direct check via typing.get_origin/typing.get_args).

Suggested change

	assert not isinstance(AgentHandler, typing.TypeVar)
	def test_route_handler_is_type_alias(self):
	"""RouteHandler is a TypeAlias (not a TypeVar)."""
	import typing
	assert not isinstance(RouteHandler, typing.TypeVar)
	typevar_type = type(typing.TypeVar("T"))
	assert not isinstance(AgentHandler, typevar_type)
	def test_route_handler_is_type_alias(self):
	"""RouteHandler is a TypeAlias (not a TypeVar)."""
	import typing
	typevar_type = type(typing.TypeVar("T"))
	assert not isinstance(RouteHandler, typevar_type)

[Copilot]

typing.TypeVar is not valid as the second argument to isinstance, so this assertion will error at runtime. Use type(typing.TypeVar("T")) (or another safe runtime check) to verify RouteHandler isn’t a TypeVar instance.

Suggested change

	# TypeAlias values are just the underlying type, not TypeVar instances
	assert not isinstance(AgentHandler, typing.TypeVar)
	def test_route_handler_is_type_alias(self):
	"""RouteHandler is a TypeAlias (not a TypeVar)."""
	import typing
	assert not isinstance(RouteHandler, typing.TypeVar)
	typevar_type = type(typing.TypeVar("T"))
	# TypeAlias values are just the underlying type, not TypeVar instances
	assert not isinstance(AgentHandler, typevar_type)
	def test_route_handler_is_type_alias(self):
	"""RouteHandler is a TypeAlias (not a TypeVar)."""
	import typing
	typevar_type = type(typing.TypeVar("T"))
	assert not isinstance(RouteHandler, typevar_type)

[Copilot]

on_user_created() delegates to on_agent_lifecycle_notification(AgentLifecycleEvent.USERCREATED, ...), but on_agent_lifecycle_notification’s route_selector currently does not compare the received activity.value_type to the requested lifecycle_event (it returns True for any known lifecycle event). This means user-created handlers will run for unrelated lifecycle events; update the selector to normalize and equality-check value_type against the requested event when lifecycle_event != "*".

[Copilot]

Because on_agent_lifecycle_notification’s selector doesn’t currently filter by the requested lifecycle_event, this on_user_workload_onboarding() registration will match any known lifecycle event (not just onboarding updates). Adjust on_agent_lifecycle_notification.route_selector to compare normalized context.activity.value_type to the requested event when not using the "*" wildcard.

[JimDaly]

After consulting with the learn platform team, closing this since it may not fix the problem.