pattern-agentic-messaging 1.2.0__tar.gz → 1.3.0__tar.gz

{pattern_agentic_messaging-1.2.0 → pattern_agentic_messaging-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pattern_agentic_messaging
-Version: 1.2.0
+Version: 1.3.0
 Summary: SLIM-powered messaging
 Author-email: Amos Joshua <amos@patternagentic.ai>
 License-File: LICENSE.md
@@ -9,6 +9,8 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.11
 Requires-Dist: slim-bindings>=1.3.0
+Provides-Extra: audit
+Requires-Dist: nats-py>=2.14.0; extra == 'audit'
 Description-Content-Type: text/markdown
 
 # Pattern Agentic Messaging
@@ -165,3 +167,7 @@ async with PASlimApp(config) as app:
         await session.send({"result": result})
 ```
 
+## Message Types
+
+All messages carry a `metadata.__pa_type` discriminator. See [docs/message-types.md](docs/message-types.md).
+

{pattern_agentic_messaging-1.2.0 → pattern_agentic_messaging-1.3.0}/README.md

@@ -152,3 +152,7 @@ async with PASlimApp(config) as app:
         await session.send({"result": result})
 ```
 
+## Message Types
+
+All messages carry a `metadata.__pa_type` discriminator. See [docs/message-types.md](docs/message-types.md).
+

pattern_agentic_messaging-1.3.0/docs/message-types.md

@@ -0,0 +1,61 @@
+# Message Types
+
+All messages carry a `metadata.__pa_type` discriminator field that identifies the payload structure.
+
+## `a2a.message`
+
+Standard A2A `Message`. Used for all conversation messages between users and agents.
+
+```json
+{
+  "role": "ROLE_USER",
+  "parts": [{"text": "hello", "mediaType": "text/plain"}],
+  "contextId": "session-uuid",
+  "messageId": "msg-uuid",
+  "metadata": {"__pa_type": "a2a.message"}
+}
+```
+
+Parsed with `pattern_agentic_messaging.a2a.Message`.
+
+## `a2a.task_status`
+
+A2A `TaskStatusUpdateEvent`. Used for task state transitions (working, completed, failed).
+
+```json
+{
+  "taskId": "task-uuid",
+  "contextId": "session-uuid",
+  "status": {
+    "state": "TASK_STATE_FAILED",
+    "message": {"role": "ROLE_AGENT", "parts": [{"text": "error details"}]}
+  },
+  "metadata": {"__pa_type": "a2a.task_status"}
+}
+```
+
+## `system_error`
+
+Framework-level error. The message was rejected before reaching the agent (e.g. invalid session token, unauthorized).
+
+```json
+{
+  "error": "invalid_session_token",
+  "detail": "Missing x-pa-session-token in message metadata",
+  "metadata": {"__pa_type": "system_error"}
+}
+```
+
+Parsed with `pattern_agentic_messaging.PASystemError`.
+
+## Utilities
+
+```python
+from pattern_agentic_messaging import (
+    PAType,           # Constants: A2A_MESSAGE, A2A_TASK_STATUS, SYSTEM_ERROR
+    PA_TYPE_KEY,      # "__pa_type"
+    tag_a2a_message,  # Adds __pa_type to an A2A message dict
+    get_pa_type,      # Reads __pa_type from a payload
+    PASystemError,    # Pydantic model for system errors
+)
+```

{pattern_agentic_messaging-1.2.0 → pattern_agentic_messaging-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pattern_agentic_messaging"
-version = "1.2.0"
+version = "1.3.0"
 description = "SLIM-powered messaging"
 authors = [
   { name="Amos Joshua", email="amos@patternagentic.ai" }
@@ -21,6 +21,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+audit = ["nats-py>=2.14.0"]
 
 
 [tool.hatch.build.targets.wheel]

{pattern_agentic_messaging-1.2.0 → pattern_agentic_messaging-1.3.0}/src/pattern_agentic_messaging/__init__.py

@@ -14,6 +14,8 @@ from .exceptions import (
 from slim_bindings import MessageContext
 from .auth import JWTClaims
 from .session_token import PatternAgentSessionToken
+from .audit import AuditPublisher
+from .message_types import PAType, PASystemError, PA_TYPE_KEY, tag_a2a_message, tag_a2a_task_status, get_pa_type
 
 __all__ = [
     "PASlimConfig",
@@ -34,4 +36,11 @@ __all__ = [
     "SerializationError",
     "SessionClosedError",
     "PatternAgentSessionToken",
+    "AuditPublisher",
+    "PAType",
+    "PASystemError",
+    "PA_TYPE_KEY",
+    "tag_a2a_message",
+    "tag_a2a_task_status",
+    "get_pa_type",
 ]

{pattern_agentic_messaging-1.2.0 → pattern_agentic_messaging-1.3.0}/src/pattern_agentic_messaging/app.py

@@ -24,6 +24,7 @@ from .config import PASlimConfig
 from .session import PASlimSession, PASlimP2PSession, PASlimGroupSession
 from .auth import create_none_auth, create_shared_secret_auth, create_jwt_auth, JWTClaims
 from .session_token import PatternAgentSessionToken
+from .message_types import PASystemError
 from .types import MessagePayload
 from .exceptions import AuthenticationError
 from .utils import parse_name
@@ -111,14 +112,14 @@ async def _call_handler(handler, session, msg, msg_ctx, injection, session_token
             token = PatternAgentSessionToken.from_metadata(msg_ctx.metadata)
         except Exception as e:
             logger.warning(f"Session token extraction failed: {e}")
-            await session.send({"system_error": "invalid_session_token", "detail": str(e)})
+            await session.send(PASystemError(error="invalid_session_token", detail=str(e)).to_payload())
             return
         if session_token_verifier:
             try:
                 await session_token_verifier(token.raw_token)
             except Exception as e:
                 logger.warning(f"Session token verification failed: {e}")
-                await session.send({"system_error": "session_token_verification_failed", "detail": str(e)})
+                await session.send(PASystemError(error="session_token_verification_failed", detail=str(e)).to_payload())
                 return
         kwargs[injection['session_token_param']] = token
     await handler(session, msg, **kwargs)
@@ -136,6 +137,7 @@ class PASlimApp:
         self._init_handlers = []
         self._running = True
         self.session_token_verifier = None
+        self._audit_publisher = None
 
     async def __aenter__(self):
         auth_type = self.config.auth_type
@@ -189,22 +191,47 @@ class PASlimApp:
             tls=tls,
             headers=self.config.custom_headers,
         )
+        logger.info(f"SLIM __aenter__: connecting to endpoint={self.config.endpoint}")
         conn_id = await service.connect_async(client_config)
+        logger.info(f"SLIM __aenter__: connected conn_id={conn_id}")
 
         local_name = parse_name(self.config.local_name)
         if auth_type == "shared_secret":
             app = service.create_app_with_secret(local_name, self.config.auth_secret)
         else:
             app = service.create_app(local_name, auth_provider, auth_verifier)
+        logger.info(f"SLIM __aenter__: app created name={self.config.local_name}")
 
         await app.subscribe_async(local_name, conn_id)
+        logger.info(f"SLIM __aenter__: subscribed name={self.config.local_name}")
 
         self._service = service
         self._app = app
         self._conn_id = conn_id
+
+        if self.config.audit_nats_url:
+            try:
+                from .audit import AuditPublisher
+                self._audit_publisher = AuditPublisher(
+                    self.config.audit_nats_url,
+                    subject_prefix=self.config.audit_nats_subject_prefix,
+                    creds_file=self.config.audit_nats_creds_file,
+                )
+                await self._audit_publisher.connect()
+            except Exception as e:
+                logger.warning(f"Audit publisher init failed (audit disabled): {e}")
+                self._audit_publisher = None
+
         return self
 
     async def __aexit__(self, exc_type, exc_val, exc_tb):
+        if self._audit_publisher:
+            try:
+                await self._audit_publisher.close()
+            except Exception:
+                pass
+            self._audit_publisher = None
+
         if self._service:
             try:
                 self._service.disconnect(self._conn_id)
@@ -502,22 +529,30 @@ class PASlimApp:
             metadata={},
         )
 
-    async def connect(self, peer_name: str) -> PASlimP2PSession:
+    async def connect(self, peer_name: str, timeout: Optional[float] = None) -> PASlimP2PSession:
         """
         Connect to a peer (P2P Active mode).
 
         Args:
             peer_name: Peer identifier (e.g., "org/namespace/app")
+            timeout: Connection timeout in seconds (default: config.connect_timeout_sec)
 
         Returns:
             PASlimP2PSession for communicating with the peer
+
+        Raises:
+            asyncio.TimeoutError: If the peer doesn't respond within the timeout
         """
+        connect_timeout = timeout or self.config.connect_timeout_sec
         peer = parse_name(peer_name)
         await self._app.set_route_async(peer, self._conn_id)
-        session = await self._app.create_session_and_wait_async(
-            self._session_config(SessionType.POINT_TO_POINT), peer
+        session = await asyncio.wait_for(
+            self._app.create_session_and_wait_async(
+                self._session_config(SessionType.POINT_TO_POINT), peer
+            ),
+            timeout=connect_timeout,
         )
-        return PASlimP2PSession(session)
+        return PASlimP2PSession(session, audit_publisher=self._audit_publisher, local_name=self.config.local_name, peer_name=peer_name)
 
     async def accept(self) -> PASlimP2PSession:
         """
@@ -527,7 +562,7 @@ class PASlimApp:
             PASlimP2PSession for the incoming connection
         """
         session = await self._app.listen_for_session_async(None)
-        return PASlimP2PSession(session)
+        return PASlimP2PSession(session, audit_publisher=self._audit_publisher, local_name=self.config.local_name)
 
     async def create_channel(self, channel_name: str, invites: list[str] = None) -> PASlimGroupSession:
         """
@@ -547,7 +582,7 @@ class PASlimApp:
         slim_session = await self._app.create_session_and_wait_async(
             self._session_config(SessionType.GROUP), channel
         )
-        session = PASlimGroupSession(slim_session)
+        session = PASlimGroupSession(slim_session, audit_publisher=self._audit_publisher, local_name=self.config.local_name, peer_name=channel_name)
 
         for invite in invites:
             participant = parse_name(invite)
@@ -564,7 +599,7 @@ class PASlimApp:
             PASlimGroupSession for the channel
         """
         session = await self._app.listen_for_session_async(None)
-        return PASlimGroupSession(session)
+        return PASlimGroupSession(session, audit_publisher=self._audit_publisher, local_name=self.config.local_name)
 
     async def listen(self) -> AsyncIterator[PASlimP2PSession]:
         """
@@ -575,7 +610,7 @@ class PASlimApp:
         """
         while True:
             session = await self._app.listen_for_session_async(None)
-            yield PASlimP2PSession(session)
+            yield PASlimP2PSession(session, audit_publisher=self._audit_publisher, local_name=self.config.local_name)
 
     async def messages(self) -> AsyncIterator[tuple[PASlimSession, MessageContext, MessagePayload]]:
         """

pattern_agentic_messaging-1.3.0/src/pattern_agentic_messaging/audit.py

@@ -0,0 +1,109 @@
+import asyncio
+import json
+import logging
+from datetime import datetime, timezone
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+class AuditPublisher:
+    def __init__(self, nats_url: str, subject_prefix: str = "pa.audit.messages", creds_file: Optional[str] = None):
+        self._nats_url = nats_url
+        self._subject_prefix = subject_prefix
+        self._creds_file = creds_file
+        self._nc = None
+        self._js = None
+        self._connect_lock = asyncio.Lock()
+
+    async def connect(self):
+        try:
+            from nats.aio.client import Client as NATS
+        except ImportError:
+            raise ImportError("nats-py is required for audit publishing. Install with: pip install pattern-agentic-messaging[audit]")
+
+        async with self._connect_lock:
+            if self._nc and self._nc.is_connected:
+                return
+            self._nc = NATS()
+            connect_opts = {"servers": [self._nats_url]}
+            if self._creds_file:
+                connect_opts["user_credentials"] = self._creds_file
+            await self._nc.connect(**connect_opts)
+            self._js = self._nc.jetstream()
+            logger.info(f"Audit publisher connected to {self._nats_url}")
+
+    async def close(self):
+        if self._nc and self._nc.is_connected:
+            await self._nc.drain()
+            await self._nc.close()
+            self._nc = None
+            self._js = None
+            logger.info("Audit publisher closed")
+
+    async def publish(
+        self,
+        payload,
+        *,
+        sender: str,
+        recipient: str,
+        tenant_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+        task_id: Optional[str] = None,
+        metadata: Optional[dict] = None,
+    ):
+        if not self._nc or not self._nc.is_connected:
+            try:
+                await self.connect()
+            except Exception:
+                logger.warning("Audit publish skipped: NATS not connected", exc_info=True)
+                return
+
+        if isinstance(payload, bytes):
+            try:
+                message = json.loads(payload)
+            except (json.JSONDecodeError, UnicodeDecodeError):
+                message = {"raw": payload.hex()}
+        elif isinstance(payload, str):
+            message = {"text": payload}
+        elif hasattr(payload, "model_dump"):
+            message = payload.model_dump(by_alias=True, exclude_none=True)
+        elif isinstance(payload, dict):
+            message = payload
+        else:
+            message = {"data": str(payload)}
+
+        envelope = {
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "sender": sender,
+            "recipient": recipient,
+            "direction": "outgoing",
+            "message": message,
+        }
+        if tenant_id:
+            envelope["tenant_id"] = tenant_id
+        if session_id:
+            envelope["session_id"] = session_id
+        if user_id:
+            envelope["user_id"] = user_id
+        if task_id:
+            envelope["task_id"] = task_id
+        if metadata:
+            envelope["metadata"] = metadata
+
+        subject_parts = [self._subject_prefix]
+        if tenant_id:
+            subject_parts.append(tenant_id)
+        if session_id:
+            subject_parts.append(session_id)
+        subject = ".".join(subject_parts)
+
+        try:
+            data = json.dumps(envelope).encode()
+            if self._js:
+                await self._js.publish(subject, data)
+            else:
+                await self._nc.publish(subject, data)
+        except Exception:
+            logger.warning(f"Audit publish failed for {subject}", exc_info=True)

{pattern_agentic_messaging-1.2.0 → pattern_agentic_messaging-1.3.0}/src/pattern_agentic_messaging/config.py

@@ -23,9 +23,13 @@ class PASlimConfig:
     jwt_token_duration: timedelta = field(default_factory=lambda: _DEFAULT_TOKEN_DURATION)
     max_retries: int = 5
     timeout: timedelta = field(default_factory=lambda: timedelta(seconds=5))
+    connect_timeout_sec: float = 30.0
     mls_enabled: bool = True
     message_discriminator: Optional[str] = None
     custom_headers: Optional[dict[str, str]] = None
+    audit_nats_url: Optional[str] = None
+    audit_nats_subject_prefix: str = "pa.audit.messages"
+    audit_nats_creds_file: Optional[str] = None
 
     def with_no_auth(self) -> PASlimConfig:
         self.auth_type = "none"

pattern_agentic_messaging-1.3.0/src/pattern_agentic_messaging/message_types.py

@@ -0,0 +1,51 @@
+from typing import Any, Optional
+from pydantic import BaseModel
+
+PA_TYPE_KEY = "__pa_type"
+
+
+class PAType:
+    A2A_MESSAGE = "a2a.message"
+    A2A_TASK_STATUS = "a2a.task_status"
+    A2A_TASK_ARTIFACT = "a2a.task_artifact"
+    SYSTEM_ERROR = "system_error"
+
+
+class PASystemError(BaseModel):
+    error: str
+    detail: str
+    metadata: dict[str, Any] = {}
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "error": self.error,
+            "detail": self.detail,
+            "metadata": {**self.metadata, PA_TYPE_KEY: PAType.SYSTEM_ERROR},
+        }
+
+    @classmethod
+    def from_payload(cls, payload: dict[str, Any]) -> "PASystemError":
+        return cls(
+            error=payload.get("error", "unknown"),
+            detail=payload.get("detail", ""),
+            metadata={k: v for k, v in payload.get("metadata", {}).items() if k != PA_TYPE_KEY},
+        )
+
+
+def tag_a2a_message(payload: dict[str, Any]) -> dict[str, Any]:
+    meta = payload.get("metadata") or {}
+    meta[PA_TYPE_KEY] = PAType.A2A_MESSAGE
+    payload["metadata"] = meta
+    return payload
+
+
+def tag_a2a_task_status(payload: dict[str, Any]) -> dict[str, Any]:
+    meta = payload.get("metadata") or {}
+    meta[PA_TYPE_KEY] = PAType.A2A_TASK_STATUS
+    payload["metadata"] = meta
+    return payload
+
+
+def get_pa_type(payload: dict[str, Any]) -> Optional[str]:
+    meta = payload.get("metadata") or {}
+    return meta.get(PA_TYPE_KEY)

{pattern_agentic_messaging-1.2.0 → pattern_agentic_messaging-1.3.0}/src/pattern_agentic_messaging/pool.py

@@ -53,11 +53,14 @@ class SlimConnectionPool:
 
     async def acquire(self, key: str, local_name: str) -> PASlimApp:
         lock = await self._get_lock(key)
+        logger.info(f"SLIM pool acquire: waiting for lock key={key}")
 
         async with lock:
+            logger.info(f"SLIM pool acquire: lock acquired key={key}")
             if key not in self._apps:
                 config = replace(self._template, local_name=local_name)
                 app = PASlimApp(config)
+                logger.info(f"SLIM pool: connecting app key={key} name={local_name} endpoint={config.endpoint}")
                 await app.__aenter__()
                 self._apps[key] = app
                 self._refcounts[key] = 0

{pattern_agentic_messaging-1.2.0 → pattern_agentic_messaging-1.3.0}/src/pattern_agentic_messaging/session.py

@@ -6,12 +6,14 @@ from datetime import timedelta
 from .types import MessagePayload
 from .messages import encode_message, decode_message
 from .exceptions import SessionClosedError, TimeoutError as PATimeoutError
+from .session_token import SESSION_TOKEN_METADATA_KEY
+from .message_types import tag_a2a_message
 from .utils import parse_name
 
 logger = logging.getLogger(__name__)
 
 class PASlimSession:
-    def __init__(self, slim_session):
+    def __init__(self, slim_session, *, audit_publisher=None, local_name: str = "", peer_name: str = ""):
         self._session = slim_session
         self._session_id = str(uuid.uuid4())
         self.context: Dict[str, Any] = {}
@@ -21,6 +23,9 @@ class PASlimSession:
         self._pending_requests: dict[str, asyncio.Future] = {}
         self._closed = False
         self._outgoing_metadata: dict[str, str] = {}
+        self._audit_publisher = audit_publisher
+        self._local_name = local_name
+        self._peer_name = peer_name
 
     @property
     def session_id(self) -> str:
@@ -34,6 +39,10 @@ class PASlimSession:
                 payload = received.payload
                 decoded = decode_message(payload)
 
+                incoming_metadata = getattr(msg_ctx, 'metadata', None) or {}
+                if SESSION_TOKEN_METADATA_KEY in incoming_metadata:
+                    self._outgoing_metadata[SESSION_TOKEN_METADATA_KEY] = incoming_metadata[SESSION_TOKEN_METADATA_KEY]
+
                 if isinstance(decoded, dict) and "_request_id" in decoded:
                     request_id = decoded["_request_id"]
                     if request_id in self._pending_requests:
@@ -93,6 +102,22 @@ class PASlimSession:
         data = encode_message(payload)
         merged = {**self._outgoing_metadata, **(metadata or {})}
         await self._session.publish_and_wait_async(data, None, merged or None)
+        if self._audit_publisher:
+            try:
+                from .session_token import PatternAgentSessionToken
+                token = PatternAgentSessionToken.from_metadata(merged) if merged else None
+                audit_payload = tag_a2a_message(dict(payload)) if isinstance(payload, dict) else payload
+                await self._audit_publisher.publish(
+                    audit_payload,
+                    sender=self._local_name,
+                    recipient=self._peer_name,
+                    tenant_id=token.tenant_id if token else None,
+                    session_id=token.session_id if token else None,
+                    user_id=token.user_id if token else None,
+                    task_id=payload.get("taskId") if isinstance(payload, dict) else None,
+                )
+            except Exception:
+                logger.debug("Audit publish failed", exc_info=True)
 
     def on_message(self, callback: Callable[[Any], None]):
         self._callbacks.append(callback)

{pattern_agentic_messaging-1.2.0 → pattern_agentic_messaging-1.3.0}/uv.lock

@@ -20,6 +20,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/cb/b1/3846dd7f199d53cb17f49cba7e651e9ce294d8497c8c150530ed11865bb8/iniconfig-2.3.0-py3-none-any.whl", hash = "sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12", size = 7484, upload-time = "2025-10-18T21:55:41.639Z" },
 ]
 
+[[package]]
+name = "nats-py"
+version = "2.14.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c3/f8/b956c4621ba88748ed707c52e69f95b7a50c8914e750edca59a5bef84a76/nats_py-2.14.0.tar.gz", hash = "sha256:4ed02cb8e3b55c68074a063aa2687087115d805d1513297da90cb2068fb07bed", size = 120751, upload-time = "2026-02-23T22:44:58.988Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f9/39/0e87753df1072254bac190b33ed34b264f28f6aa9bea0f01b7e818071756/nats_py-2.14.0-py3-none-any.whl", hash = "sha256:4116f5d2233ce16e63c3d5538fa40a5e207f75fcf42a741773929ddf1e29d19d", size = 82259, upload-time = "2026-02-23T22:45:00.152Z" },
+]
+
 [[package]]
 name = "packaging"
 version = "26.0"
@@ -31,12 +40,17 @@ wheels = [
 
 [[package]]
 name = "pattern-agentic-messaging"
-version = "1.1.0"
+version = "1.2.0"
 source = { editable = "." }
 dependencies = [
     { name = "slim-bindings" },
 ]
 
+[package.optional-dependencies]
+audit = [
+    { name = "nats-py" },
+]
+
 [package.dev-dependencies]
 dev = [
     { name = "pytest" },
@@ -44,7 +58,11 @@ dev = [
 ]
 
 [package.metadata]
-requires-dist = [{ name = "slim-bindings", specifier = ">=1.3.0" }]
+requires-dist = [
+    { name = "nats-py", marker = "extra == 'audit'", specifier = ">=2.9.0" },
+    { name = "slim-bindings", specifier = ">=1.3.0" },
+]
+provides-extras = ["audit"]
 
 [package.metadata.requires-dev]
 dev = [