agent-nebula-secureagent 5.0.0__py3-none-any.whl

agent_nebula_secureagent/__init__.py

@@ -0,0 +1,46 @@
+"""Public API for Agent Nebula SecureAgent."""
+from agent_nebula_platform.skills import SkillInvocation, SkillResult
+
+from .a2ui import create_memory_a2ui_session_service
+from .discovery import DiscoveredAgent, DiscoveredSkill
+from .execution_trace import execution_trace
+from .llm import LlmCostEstimator, LlmUsageObserver, LlmUsageRecord
+from .logging import (
+    SecureAgentLoggingConfiguration,
+    configure_console_logger,
+    create_utc_formatter,
+    create_uvicorn_log_config,
+    load_logging_configuration,
+)
+from .exceptions import (
+    SecureAgentConfigurationError,
+    SecureAgentError,
+    SecureAgentProtocolError,
+    SecureAgentSkillRegistrationError,
+)
+from .protocol import ProtocolRole, ProtocolType
+from .secure_agent import SecureAgent
+
+__all__ = [
+    "create_memory_a2ui_session_service",
+    "DiscoveredAgent",
+    "DiscoveredSkill",
+    "execution_trace",
+    "SecureAgentLoggingConfiguration",
+    "configure_console_logger",
+    "create_utc_formatter",
+    "create_uvicorn_log_config",
+    "load_logging_configuration",
+    "LlmCostEstimator",
+    "LlmUsageObserver",
+    "LlmUsageRecord",
+    "ProtocolRole",
+    "ProtocolType",
+    "SecureAgent",
+    "SecureAgentConfigurationError",
+    "SecureAgentError",
+    "SecureAgentProtocolError",
+    "SecureAgentSkillRegistrationError",
+    "SkillInvocation",
+    "SkillResult",
+]

agent_nebula_secureagent/a2a/README.md

@@ -0,0 +1,42 @@
+# Agent Nebula SecureAgent — A2A Frozen Requirements
+
+This directory is the application-facing A2A facade. All code here MUST follow these requirements.
+
+## Frozen ownership
+
+1. `a2a-sdk` owns standard A2A models, execution, client operations, tasks, artifacts, streaming, cancellation, push notifications, and protocol bindings.
+2. `agent_nebula_platform.a2a` is the only Agent Nebula Platform A2A dependency allowed here.
+3. Code in this directory MUST NOT import `agent_nebula_platform.protocols.*` or `agent_nebula_secureagent.protocols.*`.
+4. SecureAgent adds only configuration-based construction, native `AgentExecutor` registration, lifecycle convenience, and delegation to Platform A2A integration.
+5. Public A2A boundaries use native `a2a-sdk` types. Do not create SecureAgent Message, Task, Artifact, RequestContext, EventQueue, or Client wrappers.
+6. Agent Card is authoritative for skills, interfaces, extensions, and security.
+7. Nebula-specific extension semantics come only from `agent_nebula_platform.a2a.extensions`.
+8. A2UI does not belong in this directory or in the SecureAgent A2A facade.
+9. No LLM-dependent protocol behavior is allowed.
+10. Configuration, credentials, secrets, and mutable runtime state remain external.
+
+## Frozen structure
+
+```text
+a2a/
+├── README.md
+├── __init__.py
+├── client.py
+└── server.py
+```
+
+Do not add adapters, services, factories, interfaces, models, or compatibility layers without changing this contract first.
+
+## Coding standards
+
+- Keep the facade thin and direct.
+- Prefer native SDK types in signatures and return values.
+- Do not duplicate Platform configuration, security, or extension logic.
+- Do not import legacy A2A implementation paths.
+- Do not add A2UI helpers.
+- Do not convert native SDK objects to dictionaries merely to hide the SDK.
+- Use explicit type hints and explicit imports.
+- Keep exports minimal.
+- Comments explain Agent Nebula-specific behavior, not Python syntax.
+- Fail explicitly on invalid or ambiguous configuration.
+- Tests validate the public boundary.

agent_nebula_secureagent/a2a/__init__.py

@@ -0,0 +1,5 @@
+"""SecureAgent A2A facade built only on Platform A2A and the official SDK."""
+from .client import SecureAgentA2AClient
+from .server import A2AExecutableSkill, SecureAgentA2AServer
+
+__all__ = ["A2AExecutableSkill", "SecureAgentA2AClient", "SecureAgentA2AServer"]

agent_nebula_secureagent/a2a/client.py

@@ -0,0 +1,58 @@
+"""SecureAgent construction of native A2A clients."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from a2a.client import Client
+from a2a.types import AgentCard
+from agent_nebula_platform.a2a.client import A2AClient
+from agent_nebula_platform.a2a.config import A2AClientConfigurationLoader
+from agent_nebula_platform.a2a.security import (
+    A2AClientSecurityInterceptor,
+    A2AClientSecurityResolver,
+)
+from agent_nebula_platform.a2a.security.client import (
+    A2AApiKeyCredentialProvider,
+    A2ADiscoveredOAuth2CredentialProvider,
+    A2AHttpCredentialProvider,
+    A2AMutualTlsCredentialProvider,
+    A2AOidcCredentialProvider,
+    load_static_credentials,
+)
+
+
+class SecureAgentA2AClient:
+    """Apply external configuration and expose native ``a2a-sdk`` clients."""
+
+    def __init__(self, configuration_file: Path) -> None:
+        configuration = A2AClientConfigurationLoader().load(configuration_file)
+        credentials = load_static_credentials(configuration)
+        providers = [
+            A2AApiKeyCredentialProvider(credentials),
+            A2AHttpCredentialProvider(credentials),
+            A2AOidcCredentialProvider(credentials),
+            A2AMutualTlsCredentialProvider(
+                identity_configured=configuration.tls.certificate_file is not None
+            ),
+        ]
+        if configuration.oauth is not None:
+            providers.append(
+                A2ADiscoveredOAuth2CredentialProvider(
+                    configuration=configuration.oauth,
+                    tls=configuration.tls,
+                    timeout_seconds=configuration.timeout_seconds,
+                )
+            )
+        self._security = A2AClientSecurityInterceptor(
+            A2AClientSecurityResolver(tuple(providers))
+        )
+        self._client = A2AClient(configuration, security=self._security)
+
+    async def resolve_agent_card(self, location: str) -> AgentCard:
+        return await self._client.resolve_agent_card(location)
+
+    async def connect(self, location: str) -> Client:
+        return await self._client.connect(location)
+
+    async def close(self) -> None:
+        await self._security.close()

agent_nebula_secureagent/a2a/server.py

@@ -0,0 +1,177 @@
+"""SecureAgent composition of a native A2A server."""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+import httpx
+from typing import Any
+
+from a2a.server.agent_execution import AgentExecutor, RequestContext
+from a2a.server.events import EventQueue
+from a2a.server.request_handlers import DefaultRequestHandler
+from a2a.server.tasks import InMemoryTaskStore
+from a2a.server.tasks.base_push_notification_sender import BasePushNotificationSender
+from a2a.server.tasks.inmemory_push_notification_config_store import (
+    InMemoryPushNotificationConfigStore,
+)
+
+from agent_nebula_platform.a2a.runtime import A2APlatformRuntimeComposer
+from agent_nebula_platform.a2a.config import (
+    A2AListenerConfigurationLoader,
+    A2AServerConfigurationService,
+)
+from agent_nebula_platform.a2a.extensions import (
+    ensure_a2ui_extension,
+    ensure_schema_contract_extension,
+    ensure_skill_selection_extension,
+    selected_skill_id,
+    validate_executable_skills,
+)
+from agent_nebula_platform.a2a.security import (
+    A2AAuthorizedRequestHandler,
+    A2AServerSecurityFactory,
+)
+from agent_nebula_platform.a2a.security.server import A2AConfiguredSecurityLoader
+from agent_nebula_platform.a2ui.configuration import A2UIConfiguration
+
+
+
+@dataclass(frozen=True, slots=True)
+class A2AExecutableSkill:
+    """Bind one advertised skill identifier to its native SDK executor."""
+
+    skill_id: str
+    executor: AgentExecutor
+    schema_contract_id: str | None = None
+    input_schema: Mapping[str, Any] | None = None
+    output_schema: Mapping[str, Any] | None = None
+
+
+class _SkillDispatcher(AgentExecutor):
+    """Dispatch only the Nebula skill-selection extension; execution stays native."""
+
+    def __init__(self, skills: tuple[A2AExecutableSkill, ...]) -> None:
+        self._skills = {skill.skill_id: skill.executor for skill in skills}
+        self._task_skills: dict[str, str] = {}
+
+    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
+        skill_id = selected_skill_id(
+            metadata=context.metadata,
+            requested_extensions=context.requested_extensions,
+        )
+        if skill_id is None:
+            if len(self._skills) != 1:
+                raise ValueError(
+                    "Multi-skill A2A agent requires the Nebula skill-selection extension"
+                )
+            skill_id = next(iter(self._skills))
+        executor = self._skills.get(skill_id)
+        if executor is None:
+            raise ValueError(f"Selected A2A skill is not registered: {skill_id}")
+
+        # Authentication and skill authorization are complete before a2a-sdk
+        # invokes this dispatcher. This class only routes the selected skill to
+        # its application AgentExecutor.
+
+        if context.task_id is not None:
+            self._task_skills[context.task_id] = skill_id
+        await executor.execute(context, event_queue)
+
+    async def cancel(self, context: RequestContext, event_queue: EventQueue) -> None:
+        skill_id = self._task_skills.get(context.task_id or "")
+        if skill_id is None and len(self._skills) == 1:
+            skill_id = next(iter(self._skills))
+        if skill_id is None:
+            raise ValueError("Cannot route cancellation without the selected skill")
+        try:
+            await self._skills[skill_id].cancel(context, event_queue)
+        finally:
+            if context.task_id is not None:
+                self._task_skills.pop(context.task_id, None)
+
+
+class SecureAgentA2AServer:
+    """Compose Platform A2A configuration/security with native SDK execution."""
+
+    def __init__(
+        self,
+        *,
+        configuration_file: Path,
+        skills: tuple[A2AExecutableSkill, ...],
+        application_config: Path,
+        nebula_config: Path | None,
+        a2ui_config: Path | None,
+    ) -> None:
+        server = A2AServerConfigurationService().load(configuration_file)
+        listener = A2AListenerConfigurationLoader().load(configuration_file)
+        validate_executable_skills(server.agent_card, tuple(skill.skill_id for skill in skills))
+        ensure_skill_selection_extension(server.agent_card, required=False)
+        ensure_schema_contract_extension(server.agent_card, skills)
+        if a2ui_config is not None:
+            a2ui = A2UIConfiguration.load(a2ui_config)
+            if a2ui.enabled:
+                ensure_a2ui_extension(
+                    server.agent_card,
+                    supported_catalog_ids=a2ui.supported_catalog_ids,
+                    accepts_inline_catalogs=a2ui.accepts_inline_catalogs,
+                )
+
+        authenticators = A2AConfiguredSecurityLoader().load(
+            configuration_file,
+            mtls_transport_enforced=listener.tls.require_client_certificate,
+        )
+        self._security = A2AServerSecurityFactory().create(
+            agent_card=server.agent_card,
+            trust_bundle_file=listener.trust_bundle_file,
+            authenticators=authenticators,
+        )
+        self._push_http_client: httpx.AsyncClient | None = None
+        push_config_store = None
+        push_sender = None
+        if server.agent_card.capabilities.push_notifications:
+            push_config_store = InMemoryPushNotificationConfigStore()
+            self._push_http_client = httpx.AsyncClient()
+            push_sender = BasePushNotificationSender(
+                self._push_http_client,
+                push_config_store,
+            )
+
+        native_handler = DefaultRequestHandler(
+            agent_executor=_SkillDispatcher(skills),
+            task_store=InMemoryTaskStore(),
+            agent_card=server.agent_card,
+            push_config_store=push_config_store,
+            push_sender=push_sender,
+            extended_agent_card=server.extended_agent_card,
+        )
+        handler = A2AAuthorizedRequestHandler(
+            inner=native_handler,
+            agent_card=server.agent_card,
+            security=self._security.service,
+        )
+        # Keep native a2a-sdk request handling, but host it inside the existing
+        # Platform Runtime. The Runtime is required for restricted configuration
+        # paths and for onboarding, health, metrics, telemetry, state and lifecycle.
+        self._runtime = A2APlatformRuntimeComposer().compose(
+            application_config=application_config,
+            server_config=configuration_file,
+            nebula_config=nebula_config,
+            server_configuration=server,
+            listener=listener,
+            request_handler=handler,
+            security=self._security,
+        )
+
+    @property
+    def application(self):
+        return self._runtime.app
+
+    def run(self) -> None:
+        self._runtime.run()
+
+    async def close(self) -> None:
+        await self._runtime.close()
+        if self._push_http_client is not None:
+            await self._push_http_client.aclose()

agent_nebula_secureagent/a2ui.py

@@ -0,0 +1,50 @@
+"""Public SecureAgent A2UI client/runtime facade.
+
+Applications import A2UI runtime types from SecureAgent rather than depending on
+Agent Nebula Platform directly. Platform remains the implementation owner; this
+module freezes the application-facing names needed by generic A2UI clients such
+as Agent Explorer and orchestrators.
+"""
+
+from __future__ import annotations
+
+from agent_nebula_platform.a2ui import (
+    A2UIActionDispatcher,
+    A2UIActionRecord,
+    A2UIComponentPolicy,
+    A2UIMessage,
+    A2UIProtocolPolicy,
+    A2UISessionService,
+    A2UISessionSnapshot,
+    A2UISurface,
+    A2UISurfaceFrame,
+    A2UISurfaceMode,
+    A2UITaskReference,
+    MemoryA2UISessionStore,
+)
+from agent_nebula_platform.platform.events import NullEventSink
+
+
+def create_memory_a2ui_session_service() -> A2UISessionService:
+    """Create an in-memory A2UI session service through the SecureAgent API."""
+
+    return A2UISessionService(
+        store=MemoryA2UISessionStore(),
+        events=NullEventSink(),
+    )
+
+
+__all__ = [
+    "A2UIActionDispatcher",
+    "A2UIActionRecord",
+    "A2UIComponentPolicy",
+    "A2UIMessage",
+    "A2UIProtocolPolicy",
+    "A2UISessionService",
+    "A2UISessionSnapshot",
+    "A2UISurface",
+    "A2UISurfaceFrame",
+    "A2UISurfaceMode",
+    "A2UITaskReference",
+    "create_memory_a2ui_session_service",
+]

agent_nebula_secureagent/discovery.py

@@ -0,0 +1,156 @@
+"""Stable developer-facing Agent Nebula discovery models."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class DiscoveredSkill:
+    """One skill advertised by a provider returned from Agent Nebula discovery."""
+
+    skill_id: str
+    name: str | None = None
+    description: str | None = None
+    required_scopes: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class DiscoveredAgent:
+    """Protocol-neutral discovery result; remote protocol facts remain non-authoritative."""
+
+    agent_id: str
+    display_name: str
+    external_agent_id: str | None = None
+    provider_id: str | None = None
+    provider_name: str | None = None
+    category: str | None = None
+    tags: tuple[str, ...] = ()
+    trust_status: str | None = None
+    lifecycle_status: str | None = None
+    agent_card_url: str | None = None
+    a2a_endpoint: str | None = None
+    protocols: tuple[str, ...] = ()
+    skills: tuple[DiscoveredSkill, ...] = ()
+    raw_document: Mapping[str, Any] = field(default_factory=dict)
+
+    @property
+    def invokable(self) -> bool:
+        """Return whether discovery supplied a location from which to resolve the Agent Card."""
+        return bool(self.agent_card_url or self.a2a_endpoint)
+
+    def require_agent_card_location(self) -> str:
+        """Return discovery bootstrap data without treating it as invocation authority.
+
+        An explicit Agent Card URL is preferred. ``a2a_endpoint`` remains only as
+        a compatibility fallback for registries that publish a base location but
+        not an Agent Card URL. Platform resolves the authoritative Agent Card
+        before selecting the actual A2A interface or security mechanism.
+        """
+        location = self.agent_card_url or self.a2a_endpoint
+        if not location:
+            raise ValueError("Discovered agent does not expose an Agent Card location")
+        return location
+
+
+class DiscoveryNormalizer:
+    """Normalize Registry response envelopes without coupling to one API revision."""
+
+    def normalize(self, payload: Mapping[str, Any] | Sequence[Any]) -> tuple[DiscoveredAgent, ...]:
+        return tuple(
+            agent
+            for record in self._records(payload)
+            if (agent := self._agent(record)) is not None
+        )
+
+    @staticmethod
+    def _records(payload: Mapping[str, Any] | Sequence[Any]) -> tuple[Mapping[str, Any], ...]:
+        if isinstance(payload, Sequence) and not isinstance(payload, (str, bytes, bytearray)):
+            return tuple(item for item in payload if isinstance(item, Mapping))
+        if not isinstance(payload, Mapping):
+            return ()
+        for key in ("items", "agents", "results"):
+            values = payload.get(key)
+            if isinstance(values, Sequence) and not isinstance(values, (str, bytes, bytearray)):
+                return tuple(item for item in values if isinstance(item, Mapping))
+        return (payload,) if any(key in payload for key in ("agent_id", "id", "external_agent_id")) else ()
+
+    @classmethod
+    def _agent(cls, record: Mapping[str, Any]) -> DiscoveredAgent | None:
+        document = cls._document(record)
+        endpoints = cls._first_mapping(record.get("endpoints"), document.get("endpoints"))
+        provider = cls._mapping(record.get("provider"))
+        agent_id = cls._first_string(record.get("agent_id"), record.get("id"), record.get("external_agent_id"), document.get("id"))
+        if agent_id is None:
+            return None
+        a2a_endpoint = cls._first_string(record.get("a2a_endpoint"), endpoints.get("primary"), endpoints.get("a2a"), document.get("url"))
+        categories = cls._strings(record.get("categories"))
+        return DiscoveredAgent(
+            agent_id=agent_id,
+            display_name=cls._first_string(record.get("display_name"), record.get("name"), document.get("name")) or agent_id,
+            external_agent_id=cls._first_string(record.get("external_agent_id"), document.get("id")),
+            provider_id=cls._first_string(record.get("provider_id"), provider.get("provider_id"), provider.get("id")),
+            provider_name=cls._first_string(record.get("provider_name"), provider.get("display_name"), provider.get("name")),
+            category=cls._first_string(record.get("category"), document.get("category")) or (categories[0] if categories else None),
+            tags=cls._strings(record.get("tags") or document.get("tags")),
+            trust_status=cls._first_string(record.get("trust_status"), record.get("trust")),
+            lifecycle_status=cls._first_string(record.get("lifecycle_status"), record.get("status")),
+            agent_card_url=cls._first_string(record.get("agent_card_url"), record.get("agent_card_uri"), endpoints.get("agent_card"), document.get("agent_card_url")),
+            a2a_endpoint=a2a_endpoint,
+            protocols=cls._strings(record.get("protocols") or document.get("protocols")),
+            skills=cls._skills(record, document),
+            raw_document=dict(record),
+        )
+
+    @classmethod
+    def _skills(cls, record: Mapping[str, Any], document: Mapping[str, Any]) -> tuple[DiscoveredSkill, ...]:
+        values = document.get("skills") or record.get("skills")
+        if not isinstance(values, Sequence) or isinstance(values, (str, bytes, bytearray)):
+            return ()
+        result: list[DiscoveredSkill] = []
+        for value in values:
+            if not isinstance(value, Mapping):
+                continue
+            skill_id = cls._first_string(value.get("skill_id"), value.get("id"))
+            if skill_id:
+                result.append(DiscoveredSkill(
+                    skill_id=skill_id,
+                    name=cls._first_string(value.get("name")),
+                    description=cls._first_string(value.get("description")),
+                    required_scopes=cls._strings(value.get("required_scopes")),
+                ))
+        return tuple(result)
+
+    @classmethod
+    def _document(cls, record: Mapping[str, Any]) -> Mapping[str, Any]:
+        return cls._first_mapping(
+            record.get("discovery_document"), record.get("agent_card_document"),
+            record.get("agent_card"), record.get("document"), record.get("card")
+        )
+
+    @staticmethod
+    def _mapping(value: Any) -> Mapping[str, Any]:
+        return value if isinstance(value, Mapping) else {}
+
+    @classmethod
+    def _first_mapping(cls, *values: Any) -> Mapping[str, Any]:
+        for value in values:
+            mapped = cls._mapping(value)
+            if mapped:
+                return mapped
+        return {}
+
+    @staticmethod
+    def _first_string(*values: Any) -> str | None:
+        for value in values:
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+        return None
+
+    @staticmethod
+    def _strings(value: Any) -> tuple[str, ...]:
+        if not isinstance(value, Sequence) or isinstance(value, (str, bytes, bytearray)):
+            return ()
+        return tuple(dict.fromkeys(item.strip() for item in value if isinstance(item, str) and item.strip()))

agent_nebula_secureagent/exceptions.py

@@ -0,0 +1,17 @@
+"""Stable exceptions exposed by the SecureAgent developer API."""
+
+
+class SecureAgentError(Exception):
+    """Base exception for failures reported through the SecureAgent facade."""
+
+
+class SecureAgentConfigurationError(SecureAgentError):
+    """Raised when facade or protocol configuration is invalid."""
+
+
+class SecureAgentSkillRegistrationError(SecureAgentError):
+    """Raised when a business skill cannot be registered safely."""
+
+
+class SecureAgentProtocolError(SecureAgentError):
+    """Raised when a requested protocol capability is unavailable or invalid."""

agent_nebula_secureagent/execution_trace.py

@@ -0,0 +1,82 @@
+"""Public SecureAgent facade for correlated Platform execution tracing.
+
+SecureAgent deliberately exposes only the lifecycle boundary needed by an
+application host. Agent Nebula Platform remains responsible for creating the
+low-level, transport/security-aware events generated by discovery, OAuth,
+DPoP, Agent Card resolution, and A2A operations. The application remains
+responsible for choosing the execution identifier and deciding how the
+already-sanitized events are persisted or rendered.
+
+Keeping this context manager in SecureAgent prevents application code from
+importing Platform implementation primitives directly while preserving one
+correlation context across all nested Platform operations.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator, Mapping
+from contextlib import contextmanager
+from typing import Any
+
+from agent_nebula_platform.platform.execution_trace import (
+    activate_execution_trace,
+    reset_execution_trace,
+)
+
+ExecutionTraceRecorder = Callable[[Mapping[str, Any]], None]
+
+
+@contextmanager
+def execution_trace(
+    execution_id: str,
+    *,
+    recorder: ExecutionTraceRecorder,
+) -> Iterator[None]:
+    """Correlate nested SecureAgent/Platform operations with one host execution.
+
+    This function provides the public execution-trace boundary for applications
+    built on SecureAgent. While the context is active, Platform operations can:
+
+    * attach the same execution identifier to supported outbound requests;
+    * emit semantic events for discovery, Agent Card, OAuth/DPoP, and A2A work;
+    * redact sensitive security material before an event reaches ``recorder``;
+    * forward those sanitized events to the host without coupling Platform to
+      the host's persistence, workflow, or user-interface implementation.
+
+    SecureAgent does not create or persist the execution identifier and does
+    not perform a second interpretation of Platform events. The caller owns the
+    trace lifecycle and supplies the recorder used by its observability model.
+
+    Args:
+        execution_id: Host-owned correlation identifier shared by all nested
+            Platform operations executed inside this context. Leading/trailing
+            whitespace is ignored and a blank identifier is rejected.
+        recorder: Host callback that receives sanitized Platform event
+            mappings. Each event is copied before forwarding so host code cannot
+            mutate the Platform-owned event object.
+
+    Raises:
+        ValueError: If ``execution_id`` is empty or contains only whitespace.
+
+    Notes:
+        The previous Platform context is restored in ``finally``. This makes
+        nesting safe and prevents a failed workflow from leaking its execution
+        correlation into later requests handled by the same process/context.
+    """
+
+    normalized_execution_id = execution_id.strip()
+    if not normalized_execution_id:
+        raise ValueError("execution_id must not be blank")
+
+    def forward(event: dict[str, Any]) -> None:
+        # Platform has already applied its security redaction boundary. Copying
+        # here protects the Platform-owned event object from host-side mutation.
+        recorder(dict(event))
+
+    token = activate_execution_trace(normalized_execution_id, recorder=forward)
+    try:
+        yield
+    finally:
+        # Always restore the prior ContextVar token, including exception paths.
+        # This is required for nested traces and long-lived async server workers.
+        reset_execution_trace(token)

agent_nebula_secureagent/llm.py

@@ -0,0 +1,13 @@
+"""Public LLM observability facade for SecureAgent applications.
+
+Applications can record provider-reported LLM usage without importing Agent
+Nebula Platform implementation modules directly.
+"""
+
+from agent_nebula_platform.platform.llm import (
+    LlmCostEstimator,
+    LlmUsageObserver,
+    LlmUsageRecord,
+)
+
+__all__ = ["LlmCostEstimator", "LlmUsageObserver", "LlmUsageRecord"]