refactor(plugins): decouple plugin framework from gateway observability service

[araujof]

Description

Removes the plugin framework's direct dependency on mcpgateway.db.SessionLocal and mcpgateway.services.observability_service by introducing a protocol-based observability abstraction with dependency injection.

Closes: #2828

Problem

The plugin framework's _execute_with_timeout method imported SessionLocal and ObservabilityService directly from the gateway, creating a tight coupling that prevented the framework from operating standalone. This also required the plugin framework to manage database sessions for tracing — a concern that belongs to the host application.

Solution

• Introduced ObservabilityProvider protocol and NullObservability no-op default in a new observability.py module
• Added a current_trace_id ContextVar owned by the plugin framework (replacing the one imported from the gateway's observability service)
• PluginExecutor and PluginManager now accept an optional observability parameter via constructor injection
• get_plugin_manager() forwards the observability provider to the manager
• The host application (mcpgateway) can inject its own implementation at startup; the framework operates without tracing when none is provided

Dependency direction (before → after)

# Before: circular
plugin framework ──imports──> mcpgateway.db, mcpgateway.services.observability_service

# After: clean inversion
mcpgateway ──injects──> plugin framework (ObservabilityProvider)

Changes

File	Change
mcpgateway/plugins/framework/observability.py	New — ObservabilityProvider protocol, NullObservability default, current_trace_id ContextVar
mcpgateway/plugins/framework/manager.py	PluginExecutor and PluginManager accept observability param; _execute_with_timeout uses injected provider instead of direct gateway imports
mcpgateway/plugins/framework/__init__.py	get_plugin_manager() accepts observability param; ObservabilityProvider added to __all__
tests/unit/.../test_observability.py	New — 5 tests: DI injection with tracing, no trace_id, no provider, NullObservability, executor injection
tests/unit/.../test_manager_coverage.py	Updated TestExecuteWithTimeout to test against injected provider instead of mocking mcpgateway.db/mcpgateway.services

Additional Changes

A few tests in tests/unit/../test_http_auth_integration.py were failing on dev environment when running the coverage target. Solution: Reset Starlette's cached middleware_stack after injecting the mock plugin manager so the middleware chain is rebuilt with the mock, and restore it afterward to avoid side effects on other tests.

Test plan

• All unit tests pass
• All doctests pass
• New observability tests verify: span creation/completion with injected provider, graceful no-op without trace_id, graceful no-op without provider, provider failure fallback

[crivetimihai]

Thanks for this clean decoupling work, @araujof. The Protocol + DI approach is the right pattern. Two critical issues:

1. Two independent current_trace_id ContextVars (silent tracing breakage)
mcpgateway/plugins/framework/observability.py:15 creates a new ContextVar("current_trace_id"), but the gateway's observability middleware sets the original one at mcpgateway/services/observability_service.py:53. These are two distinct Python objects despite sharing the same name string. After this PR, _execute_with_timeout imports from the plugin framework's copy, which the middleware never populates — trace_id will always be None at runtime and plugin spans silently stop recording.

2. No gateway-side adapter wiring
There is no class implementing ObservabilityProvider that bridges to ObservabilityService. And main.py:187 still calls PluginManager(_config_file) without passing observability=. So even after merge, self.observability will be None on the executor, making this a no-op. The PR needs a concrete adapter and it must be passed at the main.py call site.

Minor: The Borg singleton PluginManager.__init__ only sets _executor.observability inside the not self._initialized block, so a second call with a different provider silently drops it.

[araujof]

Thanks for this clean decoupling work, @araujof. The Protocol + DI approach is the right pattern. Two critical issues:

1. Two independent current_trace_id ContextVars (silent tracing breakage) mcpgateway/plugins/framework/observability.py:15 creates a new ContextVar("current_trace_id"), but the gateway's observability middleware sets the original one at mcpgateway/services/observability_service.py:53. These are two distinct Python objects despite sharing the same name string. After this PR, _execute_with_timeout imports from the plugin framework's copy, which the middleware never populates — trace_id will always be None at runtime and plugin spans silently stop recording.

2. No gateway-side adapter wiring There is no class implementing ObservabilityProvider that bridges to ObservabilityService. And main.py:187 still calls PluginManager(_config_file) without passing observability=. So even after merge, self.observability will be None on the executor, making this a no-op. The PR needs a concrete adapter and it must be passed at the main.py call site.

Minor: The Borg singleton PluginManager.__init__ only sets _executor.observability inside the not self._initialized block, so a second call with a different provider silently drops it.

Thanks, working on it.