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

agent_nebula_platform/__init__.py

@@ -0,0 +1,77 @@
+"""Public API for the pluggable Agent Runtime integration layer."""
+
+from .a2ui.session import (
+    A2UIActionRecord,
+    A2UISessionService,
+    A2UISessionSnapshot,
+    A2UISurfaceFrame,
+    A2UISurfaceMode,
+    A2UITaskReference,
+)
+from .platform.capabilities import (
+    RuntimeCapability,
+    capability_catalog,
+    require_available,
+)
+from .platform.context import RuntimeContext
+from .platform.events import (
+    EventSink,
+    NullEventSink,
+    PythonLoggingEventSink,
+    RuntimeEvent,
+)
+from .platform.execution_trace import (
+    EXECUTION_ID_HEADER,
+    SECURITY_TRACE_HEADER,
+    activate_execution_trace,
+    current_execution_trace,
+    reset_execution_trace,
+)
+from .platform.health import HealthStatus, RuntimeHealthService
+from .platform.llm import LlmCostEstimator, LlmUsageObserver, LlmUsageRecord
+from .platform.metrics import MetricsRegistry, MetricsSnapshot
+from .platform.runtime import AgentRuntime
+from .platform.scheduler import JobTriggerType, RuntimeScheduler, ScheduledJob
+from .platform.services import RuntimeServiceRegistry
+from .platform.state import JsonFileStateStore, MemoryStateStore, RuntimeStateStore
+from .platform.telemetry import TelemetryEvent, TelemetryService, TelemetrySeverity
+
+__all__ = [
+    "EXECUTION_ID_HEADER",
+    "SECURITY_TRACE_HEADER",
+    "A2UIActionRecord",
+    "A2UISessionService",
+    "A2UISessionSnapshot",
+    "A2UISurfaceFrame",
+    "A2UISurfaceMode",
+    "A2UITaskReference",
+    "AgentRuntime",
+    "EventSink",
+    "HealthStatus",
+    "JobTriggerType",
+    "JsonFileStateStore",
+    "MemoryStateStore",
+    "LlmCostEstimator",
+    "LlmUsageObserver",
+    "LlmUsageRecord",
+    "MetricsRegistry",
+    "MetricsSnapshot",
+    "NullEventSink",
+    "PythonLoggingEventSink",
+    "RuntimeCapability",
+    "RuntimeContext",
+    "RuntimeEvent",
+    "RuntimeHealthService",
+    "RuntimeScheduler",
+    "RuntimeServiceRegistry",
+    "RuntimeStateStore",
+    "ScheduledJob",
+    "TelemetryEvent",
+    "TelemetryService",
+    "TelemetrySeverity",
+    "activate_execution_trace",
+    "capability_catalog",
+    "current_execution_trace",
+    "require_available",
+    "reset_execution_trace",
+]

agent_nebula_platform/a2a/README.md

@@ -0,0 +1,60 @@
+# Agent Nebula Platform — A2A Frozen Requirements
+
+This directory is the clean Agent Nebula integration boundary on top of the official `a2a-sdk`. **All code changes under this directory MUST follow this document.**
+
+## Frozen ownership
+
+1. `a2a-sdk` is authoritative for standard A2A protocol functionality.
+2. This package contains only Agent Nebula functionality required on top of `a2a-sdk`: configuration integration, security integration, and Nebula-specific extension semantics.
+3. Do not duplicate or wrap standard `a2a-sdk` models or operations, including AgentCard, AgentSkill, Message, Task, Artifact, AgentExecutor, RequestContext, EventQueue, Client operations, streaming, cancellation, push notifications, or protocol bindings.
+4. Public boundaries use and return native `a2a-sdk` types. Do not convert native models to dictionaries merely to hide the SDK.
+5. Agent Card is authoritative for interfaces, skills, capabilities, extensions, and security declarations.
+6. A2A extensions use the standard A2A extension mechanism. Nebula code implements only Nebula-specific extension semantics.
+7. A2UI protocol functionality does not belong in Platform. No A2UI surface, component, action, session, result-mapping, or rendering implementation may be added here.
+8. No LLM-dependent protocol behavior is allowed.
+9. Configuration, secrets, credentials, and mutable runtime state remain external to source code.
+10. Legacy compatibility code stays outside this directory and must not be imported by this directory.
+
+## Frozen structure
+
+```text
+a2a/
+├── README.md
+├── __init__.py
+├── client.py
+├── server.py
+├── config/
+│   ├── __init__.py
+│   ├── client.py
+│   └── server.py
+├── security/
+│   ├── __init__.py
+│   ├── client.py
+│   └── server.py
+└── extensions/
+    ├── __init__.py
+    ├── health.py
+    ├── schema_contract.py
+    └── skill_selection.py
+```
+
+Do not add `models`, `services`, `adapters`, `interfaces`, `factories`, `plugins`, `execution`, or similar layering without first changing this frozen contract.
+
+## Coding standards
+
+- Keep modules small in responsibility and code paths direct.
+- Prefer composition of official SDK objects over Agent Nebula wrappers.
+- Use explicit type hints and native SDK types at public boundaries.
+- Do not use wildcard imports. Keep package exports minimal and explicit.
+- Do not duplicate constants or protocol definitions.
+- Do not add speculative abstractions for hypothetical future implementations.
+- Do not add compatibility aliases or dead migration code to this tree.
+- Comments explain Agent Nebula-specific behavior or standards boundaries, not Python syntax.
+- Configuration errors must fail explicitly; do not silently invent defaults for protocol/security facts advertised by an Agent Card.
+- Security must integrate through official A2A SDK extension points such as client interceptors and server call-context builders.
+- New functionality requires tests at the public boundary.
+- A patch is not complete until formatting/static checks, imports, and targeted tests pass. Runtime success must not be claimed unless runtime execution occurred.
+
+## Change test
+
+Before adding code here, ask: **Would this functionality exist without Agent Nebula configuration, security, or a Nebula-specific extension?** If yes, it belongs to `a2a-sdk` or another standard library, not here.

agent_nebula_platform/a2a/__init__.py

@@ -0,0 +1,8 @@
+"""Agent Nebula integration layer for the official A2A SDK.
+
+Keep this package initializer side-effect free.  Configuration, security and
+runtime modules import one another through explicit submodules; eagerly
+importing the server here creates cycles while Platform presets are loading.
+"""
+
+__all__: list[str] = []

agent_nebula_platform/a2a/client.py

@@ -0,0 +1,105 @@
+"""Native a2a-sdk client construction with Agent Nebula configuration and security."""
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from urllib.parse import urlsplit, urlunsplit
+import httpx
+from a2a.client import A2ACardResolver, Client, ClientConfig, ClientFactory
+from a2a.types import AgentCard
+from a2a.utils.constants import TransportProtocol
+from .config.client import A2AClientConfiguration
+from .security.client import A2AClientSecurityInterceptor
+
+class A2AClient:
+    """Resolve Agent Cards and return native ``a2a-sdk`` clients."""
+    def __init__(self, configuration: A2AClientConfiguration, *, security: A2AClientSecurityInterceptor | None = None) -> None:
+        self.configuration = configuration
+        self.security = security
+
+    async def resolve_agent_card(self, location: str) -> AgentCard:
+        base_url, card_path = self._resolution_target(location)
+        async with self._http_client() as http_client:
+            return await A2ACardResolver(http_client, base_url).get_agent_card(relative_card_path=card_path)
+
+    async def connect(self, location: str) -> Client:
+        return self.create(await self.resolve_agent_card(location))
+
+    def create(self, agent_card: AgentCard) -> Client:
+        interceptors = [self.security] if self.security is not None else []
+        config = ClientConfig(
+            streaming=self.configuration.streaming,
+            polling=self.configuration.polling,
+            httpx_client=self._http_client(),
+            grpc_channel_factory=self._grpc_channel_factory(),
+            supported_protocol_bindings=list(self.configuration.supported_protocol_bindings),
+            use_client_preference=self.configuration.use_client_preference,
+            accepted_output_modes=list(self.configuration.accepted_output_modes),
+        )
+        return ClientFactory(config).create(agent_card, interceptors)
+
+    def _resolution_target(self, location: str) -> tuple[str, str]:
+        path = self.configuration.agent_card_path or "/.well-known/agent-card.json"
+        parsed = urlsplit(location)
+        if parsed.path.endswith(path):
+            base_path = parsed.path[:-len(path)].rstrip("/")
+            return urlunsplit((parsed.scheme, parsed.netloc, base_path, "", "")), path
+        return location, path
+
+    def _http_client(self) -> httpx.AsyncClient:
+        tls = self.configuration.tls
+        verify: bool | str = True
+        cert = None
+        if tls.trust_bundle is not None:
+            verify = str(tls.trust_bundle)
+        if tls.certificate_file is not None and tls.private_key_file is not None:
+            cert = (str(tls.certificate_file), str(tls.private_key_file))
+        return httpx.AsyncClient(verify=verify, cert=cert, timeout=self.configuration.timeout_seconds)
+
+    def _grpc_channel_factory(self) -> Callable[[str], object] | None:
+        """Create the gRPC channel factory required by the official A2A SDK."""
+        if TransportProtocol.GRPC not in self.configuration.supported_protocol_bindings:
+            return None
+        try:
+            import grpc
+        except ImportError as exc:
+            raise RuntimeError(
+                'A2A gRPC client support requires the Platform "a2a-grpc" extra'
+            ) from exc
+
+        tls = self.configuration.tls
+        if not tls.enabled:
+            def create_insecure_channel(target: str) -> object:
+                authority = target.removeprefix("grpc://").removeprefix("grpcs://")
+                return grpc.aio.insecure_channel(authority)
+
+            return create_insecure_channel
+
+        root_certificates = (
+            self._read_bytes(tls.trust_bundle) if tls.trust_bundle is not None else None
+        )
+        private_key = (
+            self._read_bytes(tls.private_key_file)
+            if tls.private_key_file is not None
+            else None
+        )
+        certificate_chain = (
+            self._read_bytes(tls.certificate_file)
+            if tls.certificate_file is not None
+            else None
+        )
+        credentials = grpc.ssl_channel_credentials(
+            root_certificates=root_certificates,
+            private_key=private_key,
+            certificate_chain=certificate_chain,
+        )
+
+        def create_secure_channel(target: str) -> object:
+            authority = target.removeprefix("grpcs://").removeprefix("grpc://")
+            return grpc.aio.secure_channel(authority, credentials)
+
+        return create_secure_channel
+
+    @staticmethod
+    def _read_bytes(path: Path) -> bytes:
+        return path.read_bytes()

agent_nebula_platform/a2a/config/__init__.py

@@ -0,0 +1,4 @@
+"""A2A configuration integration."""
+from .client import A2AClientConfiguration, A2AClientConfigurationLoader
+from .server import A2AListenerConfiguration, A2AListenerConfigurationLoader, A2AServerConfiguration, A2AServerConfigurationService, A2AServerTlsConfiguration
+__all__ = ["A2AClientConfiguration", "A2AClientConfigurationLoader", "A2AListenerConfiguration", "A2AListenerConfigurationLoader", "A2AServerConfiguration", "A2AServerConfigurationService", "A2AServerTlsConfiguration"]

agent_nebula_platform/a2a/config/client.py

@@ -0,0 +1,292 @@
+"""Typed loading and validation for the dedicated A2A client configuration."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from a2a.utils.constants import TransportProtocol
+
+from agent_nebula_platform.platform.errors import ConfigurationError
+
+_SUPPORTED_BINDINGS = {
+    TransportProtocol.JSONRPC,
+    TransportProtocol.HTTP_JSON,
+    TransportProtocol.GRPC,
+}
+
+
+@dataclass(frozen=True, slots=True)
+class A2AClientTlsConfiguration:
+    """TLS mode and material used by outbound A2A transports and Agent Card discovery."""
+
+    enabled: bool = False
+    trust_bundle: Path | None = None
+    certificate_file: Path | None = None
+    private_key_file: Path | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class A2AClientCredentialConfiguration:
+    """Local secret material keyed by arbitrary remote Agent Card scheme name."""
+
+    scheme_name: str
+    secret_file: Path
+
+
+@dataclass(frozen=True, slots=True)
+class A2AClientOAuthConfiguration:
+    """Locally provisioned OAuth client identity used for discovered OAuth2 schemes."""
+
+    client_id_file: Path
+    authentication_private_key_file: Path
+    dpop_private_key_file: Path
+    key_id: str = "a2a-oauth-client"
+    algorithm: str = "ES256"
+
+
+@dataclass(frozen=True, slots=True)
+class A2AClientConfiguration:
+    """Platform-owned settings mapped to the official A2A ``ClientConfig``."""
+
+    streaming: bool
+    polling: bool
+    supported_protocol_bindings: tuple[str, ...]
+    use_client_preference: bool
+    accepted_output_modes: tuple[str, ...]
+    timeout_seconds: float
+    agent_card_path: str | None
+    tls: A2AClientTlsConfiguration
+    credentials: tuple[A2AClientCredentialConfiguration, ...] = ()
+    oauth: A2AClientOAuthConfiguration | None = None
+
+
+class A2AClientConfigurationLoader:
+    """Load ``a2aclient.conf`` without interpreting remote Agent Card security."""
+
+    def load(self, path: Path) -> A2AClientConfiguration:
+        """Parse and validate one dedicated A2A client TOML configuration file."""
+
+        configuration_path = path.expanduser().resolve()
+        if not configuration_path.is_file():
+            raise ConfigurationError(
+                "A2A client configuration file does not exist",
+                details={"path": str(configuration_path)},
+            )
+        try:
+            with configuration_path.open("rb") as stream:
+                document = tomllib.load(stream)
+        except (OSError, tomllib.TOMLDecodeError) as exc:
+            raise ConfigurationError(
+                "A2A client configuration file is invalid",
+                details={"path": str(configuration_path)},
+            ) from exc
+
+        client = self._require_table(document, "client")
+        tls = self._require_table(client, "tls", parent="client")
+        bindings = tuple(self._string_list(client, "supported_protocol_bindings"))
+        if not bindings:
+            raise ConfigurationError(
+                "A2A client must configure at least one supported protocol binding"
+            )
+        unknown = sorted(set(bindings) - _SUPPORTED_BINDINGS)
+        if unknown:
+            raise ConfigurationError(
+                "A2A client configuration contains unsupported protocol bindings",
+                details={"bindings": unknown},
+            )
+        if len(set(bindings)) != len(bindings):
+            raise ConfigurationError("A2A client protocol bindings must be unique")
+
+        timeout = self._number(client, "timeout_seconds", default=30.0)
+        if timeout <= 0:
+            raise ConfigurationError(
+                "A2A client timeout_seconds must be greater than zero"
+            )
+
+        tls_enabled = self._boolean(tls, "enabled", default=False)
+        trust_bundle = self._optional_path(
+            tls, "trust_bundle", configuration_path.parent
+        )
+        certificate_file = self._optional_path(
+            tls, "certificate_file", configuration_path.parent
+        )
+        private_key_file = self._optional_path(
+            tls, "private_key_file", configuration_path.parent
+        )
+        if (certificate_file is None) != (private_key_file is None):
+            raise ConfigurationError(
+                "A2A client TLS certificate_file and private_key_file must be configured together"
+            )
+        # A trust bundle controls certificate verification for outbound HTTPS
+        # (Agent Card, OAuth metadata/token endpoints, and HTTP A2A bindings)
+        # even when explicit client TLS/mTLS mode is disabled.  Requiring
+        # ``enabled = true`` for a CA bundle made ordinary HTTPS callers either
+        # reject valid private PKI configuration or fall back to disabled
+        # verification.  Client certificate material remains explicit mTLS
+        # configuration and therefore still requires TLS mode to be enabled.
+        if not tls_enabled and (certificate_file is not None or private_key_file is not None):
+            raise ConfigurationError(
+                "A2A client certificate material requires [client.tls].enabled = true"
+            )
+
+        credentials_table = client.get("credentials", {})
+        if not isinstance(credentials_table, dict):
+            raise ConfigurationError("A2A client [client.credentials] must be a table")
+        credentials: list[A2AClientCredentialConfiguration] = []
+        for scheme_name, entry in credentials_table.items():
+            if (
+                not isinstance(scheme_name, str)
+                or not scheme_name.strip()
+                or not isinstance(entry, dict)
+            ):
+                raise ConfigurationError(
+                    "A2A client credential entries must be named tables"
+                )
+            secret_file = self._required_path(
+                entry, "secret_file", configuration_path.parent
+            )
+            credentials.append(
+                A2AClientCredentialConfiguration(
+                    scheme_name=scheme_name.strip(), secret_file=secret_file
+                )
+            )
+
+        oauth_table = client.get("oauth")
+        oauth = None
+        if oauth_table is not None:
+            if not isinstance(oauth_table, dict):
+                raise ConfigurationError("A2A client [client.oauth] must be a table")
+            oauth = A2AClientOAuthConfiguration(
+                client_id_file=self._destination_path(
+                    oauth_table, "client_id_file", configuration_path.parent
+                ),
+                authentication_private_key_file=self._required_path(
+                    oauth_table,
+                    "authentication_private_key_file",
+                    configuration_path.parent,
+                ),
+                dpop_private_key_file=self._required_path(
+                    oauth_table, "dpop_private_key_file", configuration_path.parent
+                ),
+                key_id=str(oauth_table.get("key_id", "a2a-oauth-client")).strip(),
+                algorithm=str(oauth_table.get("algorithm", "ES256")).strip(),
+            )
+            if not oauth.key_id or not oauth.algorithm:
+                raise ConfigurationError(
+                    "A2A client OAuth key_id and algorithm must be non-empty"
+                )
+
+        agent_card_path = client.get("agent_card_path")
+        if agent_card_path is not None:
+            if not isinstance(agent_card_path, str) or not agent_card_path.strip():
+                raise ConfigurationError(
+                    "A2A client agent_card_path must be a non-empty string"
+                )
+            agent_card_path = agent_card_path.strip()
+
+        return A2AClientConfiguration(
+            streaming=self._boolean(client, "streaming", default=True),
+            polling=self._boolean(client, "polling", default=False),
+            supported_protocol_bindings=bindings,
+            use_client_preference=self._boolean(
+                client, "use_client_preference", default=False
+            ),
+            accepted_output_modes=tuple(
+                self._string_list(client, "accepted_output_modes")
+            ),
+            timeout_seconds=float(timeout),
+            agent_card_path=agent_card_path,
+            tls=A2AClientTlsConfiguration(
+                enabled=tls_enabled,
+                trust_bundle=trust_bundle,
+                certificate_file=certificate_file,
+                private_key_file=private_key_file,
+            ),
+            credentials=tuple(credentials),
+            oauth=oauth,
+        )
+
+    @staticmethod
+    def _require_table(
+        document: dict[str, Any], name: str, *, parent: str | None = None
+    ) -> dict[str, Any]:
+        value = document.get(name)
+        if not isinstance(value, dict):
+            location = f"[{parent}.{name}]" if parent else f"[{name}]"
+            raise ConfigurationError(f"A2A client configuration requires {location}")
+        return value
+
+    @staticmethod
+    def _boolean(document: dict[str, Any], name: str, *, default: bool) -> bool:
+        value = document.get(name, default)
+        if not isinstance(value, bool):
+            raise ConfigurationError(f"A2A client {name} must be a boolean")
+        return value
+
+    @staticmethod
+    def _number(document: dict[str, Any], name: str, *, default: float) -> float:
+        value = document.get(name, default)
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            raise ConfigurationError(f"A2A client {name} must be numeric")
+        return float(value)
+
+    @staticmethod
+    def _string_list(document: dict[str, Any], name: str) -> list[str]:
+        value = document.get(name, [])
+        if not isinstance(value, list) or any(
+            not isinstance(item, str) or not item.strip() for item in value
+        ):
+            raise ConfigurationError(
+                f"A2A client {name} must be a list of non-empty strings"
+            )
+        return [item.strip() for item in value]
+
+    @staticmethod
+    def _destination_path(document: dict[str, Any], name: str, base: Path) -> Path:
+        """Resolve an OAuth output path without requiring the file to exist yet."""
+        value = document.get(name)
+        if not isinstance(value, str) or not value.strip():
+            raise ConfigurationError(
+                f"A2A client OAuth {name} must be a non-empty path"
+            )
+        path = Path(value).expanduser()
+        if not path.is_absolute():
+            path = base / path
+        path = path.resolve()
+        if not path.parent.is_dir():
+            raise ConfigurationError(
+                f"A2A client OAuth {name} parent directory does not exist",
+                details={"path": str(path), "parent": str(path.parent)},
+            )
+        return path
+
+    @staticmethod
+    def _required_path(document: dict[str, Any], name: str, base: Path) -> Path:
+        value = document.get(name)
+        if not isinstance(value, str) or not value.strip():
+            raise ConfigurationError(f"A2A client TLS {name} is required")
+        return A2AClientConfigurationLoader._resolve_existing_path(value, name, base)
+
+    @staticmethod
+    def _optional_path(document: dict[str, Any], name: str, base: Path) -> Path | None:
+        value = document.get(name)
+        if value is None:
+            return None
+        if not isinstance(value, str) or not value.strip():
+            raise ConfigurationError(f"A2A client TLS {name} must be a non-empty path")
+        return A2AClientConfigurationLoader._resolve_existing_path(value, name, base)
+
+    @staticmethod
+    def _resolve_existing_path(value: str, name: str, base: Path) -> Path:
+        path = Path(value).expanduser()
+        if not path.is_absolute():
+            path = base / path
+        path = path.resolve()
+        if not path.is_file():
+            raise ConfigurationError(
+                f"A2A client TLS {name} does not exist", details={"path": str(path)}
+            )
+        return path