hermes-agent-a2a 3.2.2__py3-none-any.whl

hermes_agent_a2a/__init__.py

@@ -0,0 +1,5 @@
+"""Hermes Agent A2A plugin — auto-discovered and loaded by Hermes Agent."""
+
+from .plugin import HermesAgentA2APlugin, __version__, register
+
+__all__ = ["HermesAgentA2APlugin", "register", "__version__"]

hermes_agent_a2a/_mode2_worker.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""
+Mode 2 ephemeral A2A worker — runs as a subprocess with the hermes-agent venv.
+Reads params from stdin (JSON), writes result to stdout (JSON), errors to stderr.
+
+Usage: python _mode2_worker.py < stdin > stdout
+"""
+import sys
+import os
+import json
+import uuid
+
+MAX_STDIN_BYTES = 1 * 1024 * 1024  # 1 MB hard limit
+
+def main():
+    raw = sys.stdin.buffer.read(MAX_STDIN_BYTES + 1)
+    if len(raw) > MAX_STDIN_BYTES:
+        print("ERROR: stdin exceeds 1MB limit", file=sys.stderr)
+        sys.exit(1)
+    params = json.loads(raw)
+
+    agent_home = params["agent_home"]
+    message = params["message"]
+    timeout = params.get("timeout", 300)
+
+    # Resolve HERMES_HOME from params or environment — must be explicit for Mode 2.
+    # Inherit HERMES_HOME from parent environment if not passed in params.
+    _hermes_home = params.get("hermes_home") or os.environ.get("HERMES_HOME", "")
+    if not _hermes_home:
+        print("ERROR: hermes_home not set in params or HERMES_HOME env var", file=sys.stderr)
+        sys.exit(1)
+    _hermes_agent = os.path.join(_hermes_home, "hermes-agent")
+    _plugin_dir = os.path.dirname(os.path.abspath(__file__))
+    # Move hermes-agent to front, keep plugin dir at front if present
+    new_path = [_hermes_agent]
+    for p in sys.path:
+        if p == _hermes_agent or p == _plugin_dir or p.startswith(_plugin_dir + os.sep):
+            continue
+        new_path.append(p)
+    sys.path[:] = new_path
+
+    # HERMES_HOME controls profile resolution, SOUL loading, etc.
+    os.environ["HERMES_HOME"] = agent_home
+
+    # Re-load hermes_constants so get_hermes_home() picks up the new HERMES_HOME
+    import importlib
+    import hermes_constants
+    importlib.reload(hermes_constants)
+
+    # Load target profile's .env for API keys
+    from hermes_cli.env_loader import load_hermes_dotenv
+    load_hermes_dotenv(hermes_home=agent_home)
+
+    # Read provider and model from target profile config
+    import yaml
+    profile_config_path = os.path.join(agent_home, "config.yaml")
+    cfg = {}
+    if os.path.isfile(profile_config_path):
+        with open(profile_config_path) as f:
+            cfg = yaml.safe_load(f) or {}
+    model_cfg = cfg.get("model", {}) or {}
+    target_provider = model_cfg.get("provider", "minimax-cn") if isinstance(model_cfg, dict) else "minimax-cn"
+    target_model = model_cfg.get("default", "MiniMax-M2.7") if isinstance(model_cfg, dict) else "MiniMax-M2.7"
+
+    if target_provider == "minimax-cn":
+        target_api_mode = "anthropic_messages"
+    elif target_provider == "anthropic":
+        target_api_mode = "anthropic_messages"
+    else:
+        target_api_mode = "chat_completions"
+
+    # Resolve API credentials directly from provider registry
+    from hermes_cli.auth import resolve_api_key_provider_credentials
+    creds = resolve_api_key_provider_credentials(target_provider)
+
+    # Suppress AIAgent's startup banner — it prints emoji to stdout which
+    # would corrupt the JSON response. Capture and discard; stderr is unaffected.
+    import io
+    _orig_stdout = sys.stdout
+    sys.stdout = io.StringIO()
+    try:
+        from run_agent import AIAgent
+        agent = AIAgent(
+            max_iterations=90,
+            skip_context_files=False,
+            skip_memory=True,
+            load_soul_identity=True,
+            session_id=f"a2a-m2-{uuid.uuid4().hex[:8]}",
+            model=target_model,
+            provider=target_provider,
+            api_mode=target_api_mode,
+            api_key=creds.get("api_key"),
+            base_url=creds.get("base_url"),
+        )
+        conv_result = agent.run_conversation(message)
+    finally:
+        sys.stdout = _orig_stdout
+
+    final = ""
+    if isinstance(conv_result, dict):
+        final = conv_result.get("final_response", "") or str(conv_result)
+    else:
+        final = str(conv_result)
+
+    result = {
+        "task_id": f"a2a-m2-{uuid.uuid4().hex[:8]}",
+        "state": "completed",
+        "response": final.strip(),
+        "source": f"ephemeral:{os.path.basename(agent_home)}",
+    }
+
+    print(json.dumps(result), flush=True)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as exc:
+        print(str(exc), file=sys.stderr)
+        sys.exit(1)

hermes_agent_a2a/a2a_spec/__init__.py

@@ -0,0 +1,67 @@
+"""Google A2A-shaped helpers plus Hermes metadata extensions."""
+
+from .agent_card import (
+    Provider,
+    Skill,
+    AgentCapabilities,
+    ExtendedAgentCard,
+    build_extended_agent_card,
+    skill_names,
+    validate_skill,
+)
+from .hermes_ext import build_hermes_metadata
+from .tasks import (
+    TERMINAL_STATES,
+    build_task_cancel_payload,
+    build_task_get_payload,
+    build_task_send_payload,
+    extract_text_from_parts,
+    is_terminal_state,
+    parse_json_rpc_error,
+    parse_task_result,
+)
+from .push import (
+    AuthenticationInfo,
+    TaskPushNotificationConfig,
+    TaskPushNotificationConfigList,
+    CreateTaskPushNotificationConfigRequest,
+    CreateTaskPushNotificationConfigResponse,
+    GetTaskPushNotificationConfigRequest,
+    GetTaskPushNotificationConfigResponse,
+    ListTaskPushNotificationConfigsRequest,
+    ListTaskPushNotificationConfigsResponse,
+    DeleteTaskPushNotificationConfigRequest,
+    DeleteTaskPushNotificationConfigResponse,
+)
+
+__all__ = [
+    "TERMINAL_STATES",
+    "build_hermes_metadata",
+    "build_task_cancel_payload",
+    "build_task_get_payload",
+    "build_task_send_payload",
+    "extract_text_from_parts",
+    "is_terminal_state",
+    "parse_json_rpc_error",
+    "parse_task_result",
+    # Agent Card models (T1-3)
+    "Provider",
+    "Skill",
+    "AgentCapabilities",
+    "ExtendedAgentCard",
+    "build_extended_agent_card",
+    "skill_names",
+    "validate_skill",
+    # Push notification models (T1-1a)
+    "AuthenticationInfo",
+    "TaskPushNotificationConfig",
+    "TaskPushNotificationConfigList",
+    "CreateTaskPushNotificationConfigRequest",
+    "CreateTaskPushNotificationConfigResponse",
+    "GetTaskPushNotificationConfigRequest",
+    "GetTaskPushNotificationConfigResponse",
+    "ListTaskPushNotificationConfigsRequest",
+    "ListTaskPushNotificationConfigsResponse",
+    "DeleteTaskPushNotificationConfigRequest",
+    "DeleteTaskPushNotificationConfigResponse",
+]

hermes_agent_a2a/a2a_spec/agent_card.py

@@ -0,0 +1,112 @@
+"""Google A2A-shaped helpers plus Hermes metadata extensions."""
+
+from dataclasses import dataclass, asdict
+from typing import Optional, List
+
+
+
+# ---------------------------------------------------------------------------
+# ExtendedAgentCard dataclasses
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Provider:
+    """Google A2A ExtendedAgentCard Provider.
+
+    Per spec: organization (required), category (optional).
+    """
+    organization: str
+    category: Optional[str] = None
+
+
+@dataclass
+class Skill:
+    """Google A2A ExtendedAgentCard Skill.
+
+    Per spec: id (required), name (required), description (optional), tags (optional).
+    """
+    id: str
+    name: str
+    description: Optional[str] = None
+    tags: Optional[List[str]] = None
+
+
+@dataclass
+class AgentCapabilities:
+    """Google A2A ExtendedAgentCard AgentCapabilities.
+
+    Per spec: streaming, pushNotifications, stateTransitionHistory — all bool, default False.
+    """
+    streaming: bool = False
+    pushNotifications: bool = False
+    stateTransitionHistory: bool = False
+
+
+@dataclass
+class ExtendedAgentCard:
+    """Google A2A ExtendedAgentCard.
+
+    Combines standard AgentCard fields with ExtendedAgentCard-specific fields.
+    """
+    name: str
+    description: str
+    provider: Provider
+    agentCapabilities: AgentCapabilities
+    defaultInputModes: List[str]
+    defaultOutputModes: List[str]
+    url: Optional[str] = None
+    version: Optional[str] = None
+    documentationUrl: Optional[str] = None
+    skills: Optional[List[Skill]] = None
+
+
+def build_extended_agent_card(overrides: Optional[dict] = None) -> dict:
+    """Build a full ExtendedAgentCard dict.
+
+    Starts with base AgentCard fields and adds ExtendedAgentCard fields.
+    Merges any overrides from the argument.
+
+    Default provider: organization="Hermes Fleet", category="official"
+    """
+    card = {
+        "name": "hermes-agent",
+        "description": "Hermes fleet agent with A2A HTTP/JSON-RPC protocol support — exposes A2A server, HMAC auth, push notifications, SSE streaming, and Telegram session routing.",
+        "url": None,
+        "version": None,
+        "documentationUrl": None,
+        "provider": asdict(Provider(organization="Hermes Fleet", category="official")),
+        "agentCapabilities": asdict(AgentCapabilities()),
+        "defaultInputModes": ["text"],
+        "defaultOutputModes": ["text"],
+    }
+    if overrides:
+        for key, value in overrides.items():
+            if key in ("provider", "agentCapabilities") and isinstance(value, dict):
+                card[key] = {**card[key], **value}
+            else:
+                card[key] = value
+    return card
+
+
+# ---------------------------------------------------------------------------
+# Legacy skill helpers (pre-existing)
+# ---------------------------------------------------------------------------
+
+
+def skill_names(agent_info: dict) -> set[str]:
+    if not isinstance(agent_info, dict):
+        return set()
+    known_skills = agent_info.get("metadata", {}).get("skills", []) or agent_info.get("skills", [])
+    return {
+        str(item.get("name") or item.get("id") or "").lower()
+        for item in known_skills
+        if isinstance(item, dict) and (item.get("name") or item.get("id"))
+    }
+
+
+def validate_skill(agent_info: dict, skill: str) -> tuple[bool, list[str]]:
+    names = skill_names(agent_info)
+    if not skill or not names:
+        return True, sorted(names)
+    return skill.lower() in names, sorted(names)

hermes_agent_a2a/a2a_spec/hermes_ext.py

@@ -0,0 +1,24 @@
+"""Hermes metadata extension for Google A2A-shaped task envelopes."""
+
+from typing import Optional
+
+
+def build_hermes_metadata(
+    route: str = "protocol",
+    execution: str = "remote_a2a",
+    delivery: Optional[str] = None,
+    reply_mode: Optional[str] = None,
+    isolation: Optional[str] = None,
+) -> dict:
+    metadata = {
+        "version": "1",
+        "route": route,
+        "execution": execution,
+    }
+    if delivery:
+        metadata["delivery"] = delivery
+    if reply_mode:
+        metadata["reply_mode"] = reply_mode
+    if isolation:
+        metadata["isolation"] = isolation
+    return metadata

hermes_agent_a2a/a2a_spec/push.py

@@ -0,0 +1,122 @@
+"""Google A2A Task Push Notification models — T1-1a.
+
+Spec reference: Google A2A proto3 spec, tasks/pushNotification methods.
+"""
+from dataclasses import dataclass, field
+from typing import Optional, List
+
+
+@dataclass
+class AuthenticationInfo:
+    """Embedded auth info within TaskPushNotificationConfig.
+
+    Per spec: auth_type (string), auth_code (string, optional).
+    All fields are optional.
+    """
+    auth_type: Optional[str] = None
+    auth_code: Optional[str] = None
+
+
+@dataclass
+class TaskPushNotificationConfig:
+    """Per spec: a registered push notification config for a task.
+
+    Fields: id, task_id, push_transport_type, endpoint, authentication (opt), metadata (opt).
+    push_transport_type values: "webhook", "gcm", etc.
+    """
+    id: str
+    task_id: str
+    push_transport_type: str
+    endpoint: str
+    authentication: Optional[AuthenticationInfo] = None
+    metadata: Optional[dict] = None
+
+
+@dataclass
+class TaskPushNotificationConfigList:
+    """Wrapper for list responses.
+
+    Fields: items (list), has_more (bool).
+    """
+    items: List[TaskPushNotificationConfig] = field(default_factory=list)
+    has_more: bool = False
+
+
+@dataclass
+class CreateTaskPushNotificationConfigRequest:
+    """Create a push notification config for a task.
+
+    Fields: id, task_id, push_transport_type, endpoint, authentication (opt), metadata (opt).
+    """
+    id: str
+    task_id: str
+    push_transport_type: str
+    endpoint: str
+    authentication: Optional[AuthenticationInfo] = None
+    metadata: Optional[dict] = None
+
+
+@dataclass
+class CreateTaskPushNotificationConfigResponse:
+    """Response after creating a push notification config.
+
+    Fields: config (TaskPushNotificationConfig).
+    """
+    config: TaskPushNotificationConfig
+
+
+@dataclass
+class GetTaskPushNotificationConfigRequest:
+    """Request to retrieve a single push notification config.
+
+    Fields: task_id, config_id.
+    """
+    task_id: str
+    config_id: str
+
+
+@dataclass
+class GetTaskPushNotificationConfigResponse:
+    """Response with a single push notification config.
+
+    Fields: config (TaskPushNotificationConfig).
+    """
+    config: TaskPushNotificationConfig
+
+
+@dataclass
+class ListTaskPushNotificationConfigsRequest:
+    """Request to list all push notification configs for a task.
+
+    Fields: task_id.
+    """
+    task_id: str
+
+
+@dataclass
+class ListTaskPushNotificationConfigsResponse:
+    """Paginated list of push notification configs for a task.
+
+    Fields: items, has_more.
+    """
+    items: List[TaskPushNotificationConfig] = field(default_factory=list)
+    has_more: bool = False
+
+
+@dataclass
+class DeleteTaskPushNotificationConfigRequest:
+    """Request to delete a push notification config.
+
+    Fields: task_id, config_id.
+    """
+    task_id: str
+    config_id: str
+
+
+@dataclass
+class DeleteTaskPushNotificationConfigResponse:
+    """Response after deleting a push notification config.
+
+    Fields: config_id.
+    """
+    config_id: str

hermes_agent_a2a/a2a_spec/tasks.py

@@ -0,0 +1,201 @@
+"""Google A2A-shaped task payload builders and result parsers.
+
+Google A2A v1.0 error codes:
+  -32700  Parse error
+  -32600  Invalid Request
+  -32603  Internal error
+  -38000  Task not found
+  -38001  Task not cancelable
+  -38002  Push notification not supported
+  -38003  Invalid state transition
+  -38004  Non-idempotent task
+"""
+
+import uuid
+from typing import Optional
+
+# A2A-spec-compliant error codes
+A2A_ERR_PARSE = -32700
+A2A_ERR_INVALID_REQUEST = -32600
+A2A_ERR_INTERNAL = -32603
+A2A_ERR_TASK_NOT_FOUND = -38000
+A2A_ERR_TASK_NOT_CANCELABLE = -38001
+A2A_ERR_PUSH_NOT_SUPPORTED = -38002
+A2A_ERR_INVALID_STATE_TRANSITION = -38003
+A2A_ERR_NON_IDEMPOTENT = -38004
+
+from dataclasses import dataclass
+
+
+@dataclass
+class TaskArtifactUpdateEvent:
+    """A task artifact update event.
+
+    Emitted over SSE when a task generates an artifact (partial or final).
+
+    Attributes:
+        context_id: REQUIRED — the context ID for this task.
+        task_id:    REQUIRED — the task this artifact belongs to.
+        artifact:   REQUIRED — the artifact data dict (A2A artifact shape).
+        metadata:   optional — additional event metadata.
+    """
+    context_id: str
+    task_id: str
+    artifact: dict
+    metadata: Optional[dict] = None
+
+    def to_dict(self) -> dict:
+        """Render the event as a plain dict for SSE transport."""
+        return {
+            "kind": "artifact",
+            "contextId": self.context_id,
+            "taskId": self.task_id,
+            "artifact": self.artifact,
+            "metadata": self.metadata or {},
+        }
+
+
+import enum
+
+
+class TaskState(str, enum.Enum):
+    """Canonical task states per Google A2A v1.0 spec."""
+
+    SUBMITTED = "submitted"
+    WORKING = "working"
+    INPUT_REQUIRED = "input_required"
+    AUTH_REQUIRED = "auth_required"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELED = "canceled"
+
+
+TERMINAL_STATES = {"completed", "failed", "canceled"}
+ACTIVE_STATES = {"submitted", "working", "input_required", "auth_required"}
+AUTH_STATES = {"auth_required", "authenticated", "rejected"}
+
+
+def is_terminal_state(state: str) -> bool:
+    return str(state or "").lower() in TERMINAL_STATES
+
+
+def build_task_send_payload(
+    task_id: str,
+    message: str,
+    sender_name: str,
+    intent: str = "consultation",
+    expected_action: str = "reply",
+    skill: Optional[str] = None,
+    hermes: Optional[dict] = None,
+    request_id: Optional[str] = None,
+) -> dict:
+    metadata = {
+        "intent": intent,
+        "expected_action": expected_action,
+        "context_scope": "full",
+        "sender_name": sender_name,
+    }
+    if skill:
+        metadata["skill"] = skill
+    if hermes:
+        metadata["hermes"] = hermes
+
+    payload = {
+        "jsonrpc": "2.0",
+        "id": request_id or str(uuid.uuid4()),
+        "method": "tasks/send",
+        "params": {
+            "id": task_id,
+            "message": {
+                "message_id": str(uuid.uuid4()),
+                "role": "user",
+                "parts": [{"type": "text", "text": message}],
+                "metadata": metadata,
+            },
+        },
+    }
+    return payload
+
+
+def build_task_get_payload(task_id: str, request_id: Optional[str] = None) -> dict:
+    return {
+        "jsonrpc": "2.0",
+        "id": request_id or str(uuid.uuid4()),
+        "method": "tasks/get",
+        "params": {"id": task_id},
+    }
+
+
+def build_task_cancel_payload(task_id: str, request_id: Optional[str] = None) -> dict:
+    return {
+        "jsonrpc": "2.0",
+        "id": request_id or str(uuid.uuid4()),
+        "method": "tasks/cancel",
+        "params": {"id": task_id},
+    }
+
+
+def extract_text_from_parts(parts) -> str:
+    chunks = []
+    for part in parts or []:
+        if not isinstance(part, dict):
+            continue
+        if part.get("type") == "text":
+            text = part.get("text", "")
+            if text:
+                chunks.append(str(text))
+        elif isinstance(part.get("text"), str):
+            chunks.append(part["text"])
+    return "\n".join(chunks).strip()
+
+
+def parse_json_rpc_error(response: dict) -> str:
+    rpc_error = response.get("error") if isinstance(response, dict) else None
+    if not rpc_error:
+        return ""
+    if isinstance(rpc_error, dict):
+        return rpc_error.get("message") or str(rpc_error)
+    return str(rpc_error)
+
+
+def build_error_response(code: int, message: str, data=None, id=None) -> dict:
+    """Build a spec-compliant JSON-RPC error response: {jsonrpc, code, message, data, id}."""
+    err = {"jsonrpc": "2.0", "code": code, "message": message}
+    if data is not None:
+        err["data"] = data
+    if id is not None:
+        err["id"] = id
+    return err
+
+
+def parse_task_result(rpc_result: dict, default_task_id: str = "") -> dict:
+    rpc_result = rpc_result or {}
+    status = rpc_result.get("status", {}) if isinstance(rpc_result, dict) else {}
+    state = status.get("state", "unknown") if isinstance(status, dict) else "unknown"
+    task_id = rpc_result.get("id", default_task_id) if isinstance(rpc_result, dict) else default_task_id
+    chunks = []
+
+    for artifact in rpc_result.get("artifacts", []) or []:
+        if isinstance(artifact, dict):
+            text = extract_text_from_parts(artifact.get("parts", []))
+            if text:
+                chunks.append(text)
+
+    status_message = status.get("message", {}) if isinstance(status, dict) else {}
+    if isinstance(status_message, dict):
+        text = extract_text_from_parts(status_message.get("parts", []))
+        if text:
+            chunks.append(text)
+
+    direct_message = rpc_result.get("message", {}) if isinstance(rpc_result, dict) else {}
+    if isinstance(direct_message, dict):
+        text = extract_text_from_parts(direct_message.get("parts", []))
+        if text:
+            chunks.append(text)
+
+    return {
+        "task_id": task_id,
+        "state": state,
+        "response": "\n".join(chunks).strip(),
+        "raw_result": rpc_result,
+    }