lockstock-integrations 1.0.0__py3-none-any.whl

lockstock_a2a/__init__.py

@@ -0,0 +1,23 @@
+"""
+LockStock A2A Protocol Adapter
+-------------------------------
+Adapts LockStock Agent Cards to the A2A (Agent-to-Agent) Protocol.
+
+The A2A protocol, developed by Google and now under the Linux Foundation,
+provides a standard for agent interoperability. This adapter ensures
+LockStock agents can participate in A2A ecosystems.
+
+See: https://a2a-protocol.org/
+"""
+
+from .adapter import A2AAdapter
+from .agent_card import A2AAgentCard, A2ACapability, A2ASecurity
+from .task_handler import A2ATaskHandler
+
+__all__ = [
+    "A2AAdapter",
+    "A2AAgentCard",
+    "A2ACapability",
+    "A2ASecurity",
+    "A2ATaskHandler"
+]

lockstock_a2a/adapter.py

@@ -0,0 +1,216 @@
+"""
+LockStock A2A Protocol Adapter
+-------------------------------
+Bidirectional adapter between LockStock and A2A protocols.
+"""
+
+from typing import Dict, Any, Optional, List
+import json
+
+from lockstock_core import LockStockClient, AgentCard
+from .agent_card import A2AAgentCard, A2ACapability, A2ASecurity, A2AAuthType
+
+
+class A2AAdapter:
+    """
+    Adapter for converting between LockStock and A2A protocols.
+
+    Enables LockStock agents to participate in A2A ecosystems
+    and A2A agents to be verified through LockStock.
+    """
+
+    def __init__(
+        self,
+        endpoint: str = "https://lockstock-api-i9kp.onrender.com",
+        api_key: Optional[str] = None
+    ):
+        """
+        Initialize A2A adapter.
+
+        Args:
+            endpoint: LockStock API endpoint
+            api_key: Admin API key for management operations
+        """
+        self.endpoint = endpoint.rstrip("/")
+        self.api_key = api_key
+
+    def to_a2a_card(self, lockstock_card: Dict[str, Any]) -> A2AAgentCard:
+        """
+        Convert a LockStock agent card to A2A format.
+
+        Args:
+            lockstock_card: LockStock internal agent card
+
+        Returns:
+            A2A-compatible agent card
+        """
+        return A2AAgentCard.from_lockstock_card(
+            lockstock_card,
+            endpoint=self.endpoint
+        )
+
+    def from_a2a_card(self, a2a_card: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Convert an A2A agent card to LockStock format.
+
+        Args:
+            a2a_card: A2A protocol agent card
+
+        Returns:
+            LockStock-compatible agent card
+        """
+        metadata = a2a_card.get("metadata", {})
+        capabilities = a2a_card.get("capabilities", [])
+
+        return {
+            "agent_id": metadata.get("id", "unknown"),
+            "display_name": metadata.get("name", "Unknown Agent"),
+            "description": metadata.get("description"),
+            "capabilities": [cap.get("name") for cap in capabilities],
+            "status": "active",
+            "source": "a2a_import",
+            "a2a_metadata": {
+                "version": a2a_card.get("version"),
+                "provider": metadata.get("provider"),
+                "security": a2a_card.get("security"),
+                "endpoints": a2a_card.get("endpoints")
+            }
+        }
+
+    def to_a2a_json(self, lockstock_card: Dict[str, Any]) -> str:
+        """
+        Convert LockStock card to A2A JSON string.
+
+        Args:
+            lockstock_card: LockStock agent card
+
+        Returns:
+            JSON string in A2A format
+        """
+        a2a_card = self.to_a2a_card(lockstock_card)
+        return a2a_card.to_json()
+
+    def capability_mapping(self) -> Dict[str, str]:
+        """
+        Get mapping between LockStock capabilities and A2A capability types.
+
+        Returns:
+            Dictionary mapping LockStock to A2A capability names
+        """
+        return {
+            # LockStock -> A2A standard capability names
+            "DEPLOY": "code_execution",
+            "RESTART": "service_management",
+            "BACKUP": "data_management",
+            "ROLLBACK": "state_management",
+            "HEARTBEAT": "health_monitoring",
+            "CHECKPOINT": "state_checkpoint",
+            "TELEPORT": "agent_migration",
+
+            # Tool-based capabilities
+            "FILE_READ": "file_operations",
+            "FILE_WRITE": "file_operations",
+            "NETWORK": "network_access",
+            "SHELL_EXEC": "code_execution"
+        }
+
+    def generate_well_known_agent_card(
+        self,
+        agent_id: str,
+        name: str,
+        capabilities: List[str],
+        description: Optional[str] = None
+    ) -> str:
+        """
+        Generate a well-known agent card for A2A discovery.
+
+        In A2A, agents advertise themselves at:
+        https://your-domain.com/.well-known/agent.json
+
+        Args:
+            agent_id: Agent identifier
+            name: Agent display name
+            capabilities: List of capabilities
+            description: Optional description
+
+        Returns:
+            JSON string suitable for /.well-known/agent.json
+        """
+        a2a_capabilities = [
+            A2ACapability(
+                name=cap,
+                type="lockstock_verified",
+                description=f"LockStock-verified capability: {cap}"
+            )
+            for cap in capabilities
+        ]
+
+        security = A2ASecurity(
+            protocol="LockStock-v1",
+            auth_type=A2AAuthType.LOCKSTOCK,
+            verification_endpoint=f"{self.endpoint}/verify",
+            signing_supported=True
+        )
+
+        card = A2AAgentCard(
+            agent_id=agent_id,
+            name=name,
+            description=description or f"LockStock-secured agent: {name}",
+            capabilities=a2a_capabilities,
+            security=security,
+            task_endpoint=f"{self.endpoint}/a2a/task",
+            status_endpoint=f"{self.endpoint}/a2a/status/{agent_id}"
+        )
+
+        return card.to_json()
+
+    async def verify_a2a_agent(
+        self,
+        a2a_card: Dict[str, Any],
+        capability: str
+    ) -> Dict[str, Any]:
+        """
+        Verify an A2A agent has a claimed capability.
+
+        When an external A2A agent claims to have a capability,
+        this verifies it through their declared verification endpoint.
+
+        Args:
+            a2a_card: The A2A agent card
+            capability: Capability to verify
+
+        Returns:
+            Verification result
+        """
+        security = a2a_card.get("security", {})
+        protocol = security.get("protocol", "")
+
+        if protocol == "LockStock-v1":
+            # This is a LockStock-secured agent, verify through our system
+            verification_endpoint = security.get("verification_endpoint")
+            agent_id = a2a_card.get("metadata", {}).get("id")
+
+            if verification_endpoint and agent_id:
+                # Create client to verify
+                client = LockStockClient(
+                    agent_id=agent_id,
+                    endpoint=self.endpoint
+                )
+
+                result = await client.verify(task=capability)
+                await client.close()
+
+                return {
+                    "verified": result.authorized,
+                    "protocol": "LockStock-v1",
+                    "agent_id": agent_id,
+                    "capability": capability,
+                    "state_hash": result.state_hash
+                }
+
+        # Unknown protocol, cannot verify
+        return {
+            "verified": False,
+            "protocol": protocol,
+            "reason": f"Unknown verification protocol: {protocol}"
+        }

lockstock_a2a/agent_card.py

@@ -0,0 +1,169 @@
+"""
+A2A Agent Card Types
+---------------------
+Type definitions matching the A2A Protocol Agent Card specification.
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Optional, Dict, Any
+from enum import Enum
+import json
+
+
+class A2AAuthType(str, Enum):
+    """A2A authentication types."""
+    NONE = "none"
+    API_KEY = "api_key"
+    OAUTH2 = "oauth2"
+    BEARER = "bearer"
+    LOCKSTOCK = "lockstock"  # Our custom auth type
+
+
+@dataclass
+class A2ASecurity:
+    """A2A security configuration."""
+    protocol: str = "LockStock-v1"
+    auth_type: A2AAuthType = A2AAuthType.LOCKSTOCK
+    verification_endpoint: Optional[str] = None
+    public_key: Optional[str] = None
+    signing_supported: bool = True
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "protocol": self.protocol,
+            "auth_type": self.auth_type.value,
+            "verification_endpoint": self.verification_endpoint,
+            "public_key": self.public_key,
+            "signing_supported": self.signing_supported
+        }
+
+
+@dataclass
+class A2ACapability:
+    """A2A capability definition."""
+    name: str
+    type: str = "lockstock_verified"
+    description: Optional[str] = None
+    input_schema: Optional[Dict[str, Any]] = None
+    output_schema: Optional[Dict[str, Any]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = {
+            "name": self.name,
+            "type": self.type
+        }
+        if self.description:
+            result["description"] = self.description
+        if self.input_schema:
+            result["input_schema"] = self.input_schema
+        if self.output_schema:
+            result["output_schema"] = self.output_schema
+        return result
+
+
+@dataclass
+class A2AAgentCard:
+    """
+    A2A Protocol Agent Card.
+
+    This is the standard format for advertising agent capabilities
+    in the A2A ecosystem.
+    """
+
+    # Required fields
+    agent_id: str
+    name: str
+
+    # Optional metadata
+    version: str = "1.0"
+    description: Optional[str] = None
+    provider: str = "LockStock"
+
+    # Capabilities
+    capabilities: List[A2ACapability] = field(default_factory=list)
+
+    # Security
+    security: Optional[A2ASecurity] = None
+
+    # Endpoints
+    task_endpoint: Optional[str] = None
+    status_endpoint: Optional[str] = None
+
+    # Additional metadata
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to A2A Agent Card JSON format."""
+        return {
+            "version": self.version,
+            "metadata": {
+                "id": self.agent_id,
+                "name": self.name,
+                "description": self.description or f"LockStock-secured agent: {self.name}",
+                "provider": self.provider,
+                **self.metadata
+            },
+            "capabilities": [cap.to_dict() for cap in self.capabilities],
+            "security": self.security.to_dict() if self.security else None,
+            "endpoints": {
+                "task": self.task_endpoint,
+                "status": self.status_endpoint
+            }
+        }
+
+    def to_json(self, indent: int = 2) -> str:
+        """Convert to JSON string."""
+        return json.dumps(self.to_dict(), indent=indent)
+
+    @classmethod
+    def from_lockstock_card(
+        cls,
+        lockstock_card: Dict[str, Any],
+        endpoint: str = "https://lockstock-api-i9kp.onrender.com"
+    ) -> "A2AAgentCard":
+        """
+        Create an A2A Agent Card from a LockStock agent card.
+
+        Args:
+            lockstock_card: LockStock internal agent card
+            endpoint: LockStock API endpoint
+
+        Returns:
+            A2A-compatible agent card
+        """
+        agent_id = lockstock_card.get("agent_id", "unknown")
+
+        # Convert LockStock capabilities to A2A capabilities
+        capabilities = [
+            A2ACapability(
+                name=cap,
+                type="lockstock_verified",
+                description=f"Cryptographically verified capability: {cap}"
+            )
+            for cap in lockstock_card.get("capabilities", [])
+        ]
+
+        # Create security configuration
+        security = A2ASecurity(
+            protocol="LockStock-v1",
+            auth_type=A2AAuthType.LOCKSTOCK,
+            verification_endpoint=f"{endpoint}/verify",
+            public_key=lockstock_card.get("public_key"),
+            signing_supported=True
+        )
+
+        return cls(
+            agent_id=agent_id,
+            name=lockstock_card.get("display_name", agent_id),
+            description=lockstock_card.get("description"),
+            capabilities=capabilities,
+            security=security,
+            task_endpoint=f"{endpoint}/a2a/task",
+            status_endpoint=f"{endpoint}/a2a/status/{agent_id}",
+            metadata={
+                "fingerprint": lockstock_card.get("fingerprint"),
+                "owner_id": lockstock_card.get("owner_id"),
+                "created_at": lockstock_card.get("created_at"),
+                "status": lockstock_card.get("status", "active")
+            }
+        )

lockstock_a2a/task_handler.py

@@ -0,0 +1,294 @@
+"""
+A2A Task Handler
+-----------------
+Handler for A2A protocol task requests.
+
+The A2A protocol defines a task lifecycle with states:
+- pending: Task received but not started
+- running: Task in progress
+- completed: Task finished successfully
+- failed: Task failed
+- cancelled: Task was cancelled
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, Any, Optional, Callable, Awaitable
+from enum import Enum
+import time
+import uuid
+
+from lockstock_core import LockStockClient
+from lockstock_core.types import map_tool_to_capability
+
+
+class A2ATaskState(str, Enum):
+    """A2A task lifecycle states."""
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+@dataclass
+class A2ATask:
+    """An A2A protocol task."""
+    task_id: str
+    agent_id: str
+    capability: str
+    input_data: Dict[str, Any]
+    state: A2ATaskState = A2ATaskState.PENDING
+    output_data: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None
+    created_at: float = field(default_factory=time.time)
+    updated_at: float = field(default_factory=time.time)
+    lockstock_hash: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "task_id": self.task_id,
+            "agent_id": self.agent_id,
+            "capability": self.capability,
+            "state": self.state.value,
+            "input_data": self.input_data,
+            "output_data": self.output_data,
+            "error": self.error,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "lockstock_verification": {
+                "hash": self.lockstock_hash
+            } if self.lockstock_hash else None
+        }
+
+
+class A2ATaskHandler:
+    """
+    Handler for A2A protocol task requests.
+
+    Manages the task lifecycle while integrating with LockStock
+    for authorization and audit.
+    """
+
+    # Type for task executor functions
+    TaskExecutor = Callable[[str, Dict[str, Any]], Awaitable[Dict[str, Any]]]
+
+    def __init__(
+        self,
+        agent_id: str,
+        secret: Optional[str] = None,
+        api_key: Optional[str] = None,
+        endpoint: str = "https://lockstock-api-i9kp.onrender.com"
+    ):
+        """
+        Initialize A2A task handler.
+
+        Args:
+            agent_id: The agent's unique identifier
+            secret: The agent's HMAC secret
+            api_key: Admin API key
+            endpoint: LockStock API endpoint
+        """
+        self.client = LockStockClient(
+            agent_id=agent_id,
+            secret=secret,
+            api_key=api_key,
+            endpoint=endpoint
+        )
+        self.agent_id = agent_id
+        self._tasks: Dict[str, A2ATask] = {}
+        self._executors: Dict[str, "A2ATaskHandler.TaskExecutor"] = {}
+
+    def register_executor(
+        self,
+        capability: str,
+        executor: "A2ATaskHandler.TaskExecutor"
+    ):
+        """
+        Register an executor for a capability.
+
+        Args:
+            capability: The capability this executor handles
+            executor: Async function that executes tasks
+        """
+        self._executors[capability.upper()] = executor
+
+    async def create_task(
+        self,
+        capability: str,
+        input_data: Dict[str, Any],
+        task_id: Optional[str] = None
+    ) -> A2ATask:
+        """
+        Create a new A2A task.
+
+        Args:
+            capability: Required capability
+            input_data: Task input data
+            task_id: Optional task ID (generated if not provided)
+
+        Returns:
+            Created task
+        """
+        task_id = task_id or f"task_{uuid.uuid4().hex[:16]}"
+
+        task = A2ATask(
+            task_id=task_id,
+            agent_id=self.agent_id,
+            capability=capability.upper(),
+            input_data=input_data
+        )
+
+        self._tasks[task_id] = task
+
+        # Log task creation
+        await self.client.log_audit(
+            action="a2a_task_create",
+            status="CREATED",
+            metadata={
+                "task_id": task_id,
+                "capability": capability
+            }
+        )
+
+        return task
+
+    async def execute_task(self, task_id: str) -> A2ATask:
+        """
+        Execute a pending task.
+
+        Args:
+            task_id: Task to execute
+
+        Returns:
+            Updated task with result
+        """
+        task = self._tasks.get(task_id)
+        if not task:
+            raise ValueError(f"Task not found: {task_id}")
+
+        if task.state != A2ATaskState.PENDING:
+            raise ValueError(f"Task is not pending: {task.state}")
+
+        # Verify capability with LockStock
+        result = await self.client.verify(task=task.capability)
+
+        if not result.authorized:
+            task.state = A2ATaskState.FAILED
+            task.error = f"LockStock authorization denied: {result.reason}"
+            task.updated_at = time.time()
+            return task
+
+        task.lockstock_hash = result.state_hash
+
+        # Find executor
+        executor = self._executors.get(task.capability)
+        if not executor:
+            task.state = A2ATaskState.FAILED
+            task.error = f"No executor registered for capability: {task.capability}"
+            task.updated_at = time.time()
+            return task
+
+        # Execute
+        task.state = A2ATaskState.RUNNING
+        task.updated_at = time.time()
+
+        try:
+            output = await executor(task.capability, task.input_data)
+            task.state = A2ATaskState.COMPLETED
+            task.output_data = output
+
+            # Log success
+            await self.client.log_audit(
+                action="a2a_task_complete",
+                status="COMPLETED",
+                metadata={
+                    "task_id": task_id,
+                    "capability": task.capability
+                }
+            )
+
+        except Exception as e:
+            task.state = A2ATaskState.FAILED
+            task.error = str(e)
+
+            # Log failure
+            await self.client.log_audit(
+                action="a2a_task_fail",
+                status="FAILED",
+                metadata={
+                    "task_id": task_id,
+                    "error": str(e)
+                }
+            )
+
+        task.updated_at = time.time()
+        return task
+
+    async def get_task_status(self, task_id: str) -> Optional[A2ATask]:
+        """
+        Get task status.
+
+        Args:
+            task_id: Task identifier
+
+        Returns:
+            Task if found, None otherwise
+        """
+        return self._tasks.get(task_id)
+
+    async def cancel_task(self, task_id: str) -> Optional[A2ATask]:
+        """
+        Cancel a pending or running task.
+
+        Args:
+            task_id: Task to cancel
+
+        Returns:
+            Updated task if found
+        """
+        task = self._tasks.get(task_id)
+        if not task:
+            return None
+
+        if task.state in [A2ATaskState.COMPLETED, A2ATaskState.FAILED]:
+            return task  # Already finished
+
+        task.state = A2ATaskState.CANCELLED
+        task.updated_at = time.time()
+
+        await self.client.log_audit(
+            action="a2a_task_cancel",
+            status="CANCELLED",
+            metadata={"task_id": task_id}
+        )
+
+        return task
+
+    async def list_tasks(
+        self,
+        state: Optional[A2ATaskState] = None,
+        limit: int = 100
+    ) -> list:
+        """
+        List tasks.
+
+        Args:
+            state: Filter by state (optional)
+            limit: Maximum tasks to return
+
+        Returns:
+            List of task summaries
+        """
+        tasks = list(self._tasks.values())
+
+        if state:
+            tasks = [t for t in tasks if t.state == state]
+
+        # Sort by created_at descending
+        tasks.sort(key=lambda t: t.created_at, reverse=True)
+
+        return [t.to_dict() for t in tasks[:limit]]
+
+    async def close(self):
+        """Close the underlying client."""
+        await self.client.close()