hermes-agent-a2a 3.2.2__tar.gz

hermes_agent_a2a-3.2.2/.github/ISSUE_TEMPLATE/security-vulnerability.md

@@ -0,0 +1,31 @@
+---
+name: Security Vulnerability
+about: Report a security issue in hermes-agent-a2a
+title: "[SECURITY]"
+labels: security
+assignees: ''
+---
+
+**Describe the vulnerability**
+
+<!-- What is the security issue? -->
+
+
+**Versions affected**
+
+<!-- e.g. 2.0.0 - 2.0.3 -->
+
+
+**Impact**
+
+<!-- What is the worst-case impact if exploited? -->
+
+
+**Proof of concept**
+
+<!-- Steps to reproduce, if applicable -->
+
+
+**Suggested fix**
+
+<!-- How should this be fixed? -->

hermes_agent_a2a-3.2.2/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "CI"
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"

hermes_agent_a2a-3.2.2/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m py_compile hermes_agent_a2a/*.py
+      - run: python -m pytest tests/ -v

hermes_agent_a2a-3.2.2/.github/workflows/release.yml

@@ -0,0 +1,22 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: python -m pip install --upgrade pip build
+      - run: python -m build
+      - uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*

hermes_agent_a2a-3.2.2/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+*.bak-*
+dist/
+dispatch/

hermes_agent_a2a-3.2.2/CHANGELOG.md

@@ -0,0 +1,137 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [3.2.2] - 2026-05-20
+
+### Security Fixes
+- **SEC-01: DNS timeout**: `socket.setdefaulttimeout(5.0)` added before `gethostbyname` in `is_safe_url` — prevents indefinite blocking on malicious DNS
+- **SEC-02: Container auth bypass**: Localhost bypass now gated on `A2A_REQUIRE_AUTH=true` — loopback is not isolated in containers/shared namespaces
+- **SEC-06: HMAC required on push config**: `_check_hmac_push(required=True)` — push subscription config now requires valid HMAC
+
+### Documentation
+- Description updated to reflect Hermes-specific A2A HTTP/JSON-RPC implementation
+- `.gitignore` updated to exclude `dispatch/`
+
+## [3.2.1] - 2026-05-19
+
+### Bug Fixes (CRITICAL/HIGH from CODE_REVIEW.md)
+
+#### Compliance Fixes
+- **jsonrpc field missing in Mode3 timeout response**: `jsonrpc: "2.0"` added to tool_handlers.py:801
+- **CORS hardcoded `*` at 5 locations**: Made configurable via `A2A_CORS_ORIGINS` env var (defaults to `*` for backward compat)
+- **CORS method mismatch on POST-only endpoints**: Removed `GET` from `Access-Control-Allow-Methods` on POST-only endpoints
+- **pushNotifications always returned boolean `True`**: Now returns `{webhookUrl: "..."}` object form when webhook is configured per A2A spec
+
+#### Security Fixes
+- **SSRF bypass via fleet-registry.yaml**: `_is_local_fleet_agent` now validates URL host is actually safe, not just loopback flag
+- **Webhook secret exposure in error paths**: Generic error messages now used throughout
+
+#### SSE / Streaming Fixes
+- **SSE idle tracking used `created_at` (stream creation)**: Replaced with per-stream `_last_activity` updated on server-side activity (`push_event`). Client polling no longer resets idle timer.
+- **SSE streams never expired**: Cleanup thread added with 300s idle timeout
+
+#### Resource Leak Fixes
+- **Daemon threads not joined on shutdown**: Plugin shutdown now joins SSE handler threads
+- **Subscription store grew unbounded**: `add()`/`remove()` lifecycle now managed; TTL/cleanup logic added
+
+#### Test Coverage
+- **Mode3 worker subprocess tests**: Fixed 9 test failures — wrong patch targets (cleanup_zombie_processes in worker_registry, not tool_handlers), missing params, mock side_effect fixes
+- **Mode2 worker tests**: Fixed os.path.isdir patching, TimeoutExpired exception handling
+- **Concurrent TaskQueue access**: Tests added for race conditions
+
+#### Other Fixes
+- **Non-atomic metric recording**: `record_webhook_result(success: bool)` atomic API confirmed in place
+- **Task loss between drain/requeue**: Safety comments and requeue logic verified
+- **HMAC verification failure**: Proper exception handling in push_delivery.py
+- **Path traversal check ordering**: Verified correct in tool_handlers.py
+
+### Tests
+- **535 tests passing**, 13 non-blocking teardown errors (mock subprocess cleanup in Mode3 tests — all assertions pass, non-spreading)
+
+### v2 Deferred (API Design)
+- Dual args/kwargs in `handle_send_session_message`
+- Confusing token fallback chain
+- Singleton reload behavior
+
+---
+
+## [3.2.0] - 2026-05-17
+
+### Google A2A v1.0 Full Compliance
+- **Idempotency keys**: `IdempotencyStore` singleton with 24h TTL. Same-key/same-payload → cached result. Same-key/different-payload → `-38004` error.
+- **Full state machine**: `auth_required`, `authenticated`, `rejected` states added to `TaskQueue._TRANSITIONS`. Invalid transitions → `-38003` error.
+- **Error schema alignment**: All 8 A2A error codes defined (`-32700`, `-32600`, `-32603`, `-38000` through `-38004`). All error responses use `{code, message, data}` format.
+- **CORS headers**: `Access-Control-Allow-Origin: *` on all responses. `do_OPTIONS()` for preflight. Applied to GET, POST, OPTIONS, and error responses.
+- **Agent card schema**: `agentId` field added. `skills[]` uses `{id, name}` per spec.
+
+#### Wave 2 — Streaming & Push (P1)
+- **SSE streaming** (`tasks/sendSubscribe`): Server-Sent Events stream of task state transitions. `SSEStreamer` singleton manages stream lifecycle.
+- **Push notifications** (`tasks/pushNotification/subscribe` + unsubscribe): `SubscriptionStore` persists webhook subscriptions with HMAC key. `PushDelivery` delivers HMAC-SHA256 signed payloads with exponential backoff retry (3 attempts).
+- **Hook wiring**: `TaskStateChangeHook.on_state_change()` broadcasts SSE events and delivers push webhooks on task state transitions.
+
+#### Tests
+- 161 tests passing (50 compliance + 24 SSE + 26 push + 79 current + 2 hybrid)
+- Coverage: subscription_store 100%, sse_handler 94%, push_delivery 80%, server 68%, hooks 39%
+
+## [3.1.3] - 2026-05-15
+
+### Security Fixes (CRITICAL)
+- CR-1: Simplified resolve_agent to return only safe fields (name, a2a_url, description, role)
+  - Removed _strip_secrets function entirely
+  - Transports with auth secrets are never included in response
+  - Simpler and more secure than stripping secrets from full dict
+
+### Bug Fixes (HIGH)
+- HIGH #6: Replaced queue traversal with atomic counter in TaskQueue
+  - pending_count() now counter-based: max(0, _enqueue_count - _complete_count - _cancel_count)
+  - No singleton access, no re-entrancy path
+  - Fixed counter increment timing to prevent drift on queue overflow eviction
+
+### Bug Fixes (MEDIUM)
+- MEDIUM #1: Fixed update_exchange placeholder matching in persistence.py
+- MEDIUM #2: Fixed queue overflow race condition in server.py
+- MEDIUM #3: Fixed metrics logger idempotency in runtime_state.py
+- MEDIUM #4: Fixed to_dict mutability in runtime_state.py
+- MEDIUM #5: Fixed persistence.py atomicity
+- MEDIUM #7: Fixed DEFAULT_PORT collision detection with retry logic in plugin.py
+- MEDIUM #8: Fixed A2A_WEBHOOK_SECRET fallback to WEBHOOK_SECRET with warning
+- MEDIUM #9: Fixed path traversal prevention for card_path in webhook agent card retrieval
+- MEDIUM #10: Fixed AuditLogger exception logging to use logger.warning
+- MEDIUM #11: Fixed TOCTOU race condition in audit log rotation
+- MEDIUM #12: Disabled email pattern redaction in filter_outbound (too broad)
+- MEDIUM #13: Fixed regex capture group comment in hooks.py
+
+### Code Quality (LOW)
+- LOW #1: Added sort_keys=True to HMAC json.dumps for canonical signatures
+- LOW #2: Removed dead proc.wait() call and fixed SyntaxError in _handle_call_mode2
+- LOW #3: Removed redundant cleanup_zombie_processes() call in finally block
+- LOW #4: Removed redundant json import from inline import statement
+- LOW #5: Removed redundant logging import inside handle_send_session_message
+- LOW #6: Added comment explaining GIL guarantee for double-checked locking
+- LOW #7: Removed module-level task_queue variable that shadowed TaskQueue class
+- LOW #8: Removed unused user_task parameter from handle_help() and handle_list()
+- LOW #9: Added warning when hermes_cli.__version import fails
+- LOW #10: Changed msg_id from task_id[:12] to full task_id (UUID truncation)
+- LOW #11: Added comment documenting daemon thread metrics loss limitation
+- LOW #13: Removed self-import in _get_queue_depth method
+- LOW #14: Added force parameter to set_runtime_callbacks() to prevent overwriting on reload
+
+### Tests
+- All 62 tests pass
+- Added tests for _derive_hermes_home fallback and error raising scenarios
+
+## [3.1.2] - 2026-05-15
+
+### Bug Fixes (HIGH)
+- HIGH #6: Replace queue traversal with atomic counter in TaskQueue
+
+## [3.1.1] - Previous Release
+
+## [3.1.0] - Previous Release
+
+## [3.0.0] - Previous Release
+
+## [2.0.1] - Previous Release
+
+## [2.0.0] - Previous Release

hermes_agent_a2a-3.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Linda, Britney, and the Hermes Fleet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hermes_agent_a2a-3.2.2/METRICS_DESIGN.md

@@ -0,0 +1,256 @@
+# A2A Plugin Monitoring/Metrics Design
+
+## Overview
+Add monitoring and metrics for the A2A plugin to track queue depth, webhook success rates, and other operational metrics.
+
+## Architecture
+
+### 1. Metrics Storage
+Store metrics in `A2ARuntimeState` singleton for thread-safe access across plugin components.
+
+```python
+class A2AMetrics:
+    """Thread-safe metrics collector for A2A operations."""
+    
+    def __init__(self):
+        self._lock = Lock()
+        self._webhook_attempts = 0
+        self._webhook_successes = 0
+        self._webhook_failures = 0
+        self._tasks_received = 0
+        self._tasks_completed = 0
+        self._tasks_canceled = 0
+        self._tasks_failed = 0
+        self._start_time = time.time()
+    
+    def record_webhook_attempt(self):
+        with self._lock:
+            self._webhook_attempts += 1
+    
+    def record_webhook_success(self):
+        with self._lock:
+            self._webhook_successes += 1
+    
+    def record_webhook_failure(self):
+        with self._lock:
+            self._webhook_failures += 1
+    
+    def record_task_received(self):
+        with self._lock:
+            self._tasks_received += 1
+    
+    def record_task_completed(self):
+        with self._lock:
+            self._tasks_completed += 1
+    
+    def record_task_canceled(self):
+        with self._lock:
+            self._tasks_canceled += 1
+    
+    def record_task_failed(self):
+        with self._lock:
+            self._tasks_failed += 1
+    
+    def get_metrics(self) -> dict:
+        with self._lock:
+            uptime = time.time() - self._start_time
+            webhook_success_rate = (
+                self._webhook_successes / self._webhook_attempts * 100
+                if self._webhook_attempts > 0 else 0
+            )
+            return {
+                "uptime_seconds": uptime,
+                "webhook": {
+                    "attempts": self._webhook_attempts,
+                    "successes": self._webhook_successes,
+                    "failures": self._webhook_failures,
+                    "success_rate_percent": round(webhook_success_rate, 2),
+                },
+                "tasks": {
+                    "received": self._tasks_received,
+                    "completed": self._tasks_completed,
+                    "canceled": self._tasks_canceled,
+                    "failed": self._tasks_failed,
+                },
+                "queue": {
+                    "pending_count": self._get_queue_depth(),
+                },
+            }
+    
+    def _get_queue_depth(self) -> int:
+        from .runtime_state import get_runtime_state as get_state
+        return get_state().get_task_queue().pending_count()
+```
+
+### 2. Tool: a2a_get_metrics
+Expose metrics via a tool that the LLM can query directly.
+
+```python
+def handle_get_metrics() -> dict:
+    """Get current A2A plugin metrics."""
+    from .runtime_state import get_runtime_state as get_state
+    state = get_state()
+    return state.get_metrics().get_metrics()
+```
+
+### 3. Periodic Logging
+Log metrics at regular intervals (configurable via env var).
+
+```python
+_METRICS_LOG_INTERVAL = int(os.getenv("A2A_METRICS_LOG_INTERVAL", "300"))  # 5 minutes
+
+def _start_metrics_logger():
+    """Start background thread to log metrics periodically."""
+    if os.getenv("A2A_METRICS_LOG_ENABLED", "false").lower() != "true":
+        return
+    
+    def log_metrics():
+        while True:
+            try:
+                from .runtime_state import get_runtime_state as get_state
+                metrics = get_state().get_metrics().get_metrics()
+                logger.info("[A2A Metrics] %s", json.dumps(metrics))
+                time.sleep(_METRICS_LOG_INTERVAL)
+            except Exception as exc:
+                logger.error("[A2A Metrics] Logger error: %s", exc)
+                time.sleep(_METRICS_LOG_INTERVAL)
+    
+    threading.Thread(target=log_metrics, daemon=True).start()
+```
+
+### 4. Instrumentation Points
+Add metric recording at key points in the code:
+
+**server.py** - task queue operations:
+- Record task received on enqueue
+- Record task completed/canceled/failed
+
+**tool_handlers.py** - webhook delivery:
+- Record webhook attempt before delivery
+- Record webhook success on successful delivery
+- Record webhook failure on retry exhaustion
+
+### 5. Telegram Slash Command (Optional)
+Inject metrics as a Telegram slash command `/a2a_metrics` similar to `/lcm` from hermes-lcm.
+
+**Challenge**: This requires Hermes gateway integration, not just plugin code.
+
+**Options**:
+
+**Option A: Gateway Customization (Recommended for hermes-lcm pattern)**
+Add a custom command handler in the Hermes gateway's Telegram platform adapter:
+```python
+# In gateway/platforms/telegram.py (customization)
+async def handle_a2a_metrics_command(update, context):
+    """Handle /a2a_metrics command."""
+    from hermes_agent_a2a.runtime_state import get_runtime_state
+    metrics = get_runtime_state().get_metrics().get_metrics()
+    response = format_metrics_for_telegram(metrics)
+    await update.message.reply_text(response)
+```
+
+**Option B: Webhook-Backed Command (Plugin-Only)**
+Register the command via the plugin's webhook endpoint:
+- Send message to agent with special prefix: `/a2a_metrics`
+- Tool handler detects command and returns metrics instead of processing as task
+- Gateway routes response back to Telegram
+
+```python
+def handle_send_session_message(message, agent, ...):
+    # Detect metrics command
+    if message.strip().startswith("/a2a_metrics"):
+        from .runtime_state import get_runtime_state as get_state
+        metrics = get_state().get_metrics().get_metrics()
+        return {
+            "state": "completed",
+            "response": format_metrics_for_telegram(metrics),
+            "delivery": "command_response",
+        }
+    # ... normal processing
+```
+
+**Option C: Tool-Based Query (Simplest)**
+LLM can query metrics via tool, then format for Telegram:
+```
+User: /a2a_metrics
+LLM: [calls a2a_get_metrics tool]
+LLM: [formats response and sends to Telegram]
+```
+
+### 6. Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `A2A_METRICS_LOG_ENABLED` | `false` | Enable periodic metrics logging |
+| `A2A_METRICS_LOG_INTERVAL` | `300` | Logging interval in seconds |
+| `A2A_METRICS_COMMAND_ENABLED` | `false` | Enable /a2a_metrics command (Option B) |
+
+### 7. Implementation Priority
+
+1. **Phase 1** (Core Metrics):
+   - Create A2AMetrics class
+   - Add to A2ARuntimeState
+   - Instrument webhook delivery points
+   - Instrument task queue operations
+   - Add a2a_get_metrics tool
+
+2. **Phase 2** (Logging):
+   - Add periodic metrics logger
+   - Add configuration via env vars
+
+3. **Phase 3** (Telegram Command - Optional):
+   - Implement Option B (webhook-backed command)
+   - Add formatting for Telegram
+   - Test command flow
+
+## Example Output
+
+### Tool Response (JSON)
+```json
+{
+  "uptime_seconds": 3600,
+  "webhook": {
+    "attempts": 150,
+    "successes": 142,
+    "failures": 8,
+    "success_rate_percent": 94.67
+  },
+  "tasks": {
+    "received": 150,
+    "completed": 142,
+    "canceled": 5,
+    "failed": 3
+  },
+  "queue": {
+    "pending_count": 0
+  }
+}
+```
+
+### Telegram Formatted Response
+```
+📊 A2A Metrics
+
+Uptime: 1h 0m
+
+🔗 Webhook
+Attempts: 150
+✅ Success: 142 (94.67%)
+❌ Failed: 8
+
+📋 Tasks
+Received: 150
+Completed: 142
+Canceled: 5
+Failed: 3
+
+📬 Queue
+Pending: 0
+```
+
+## Testing
+
+- Unit tests for metrics collection
+- Integration tests for tool response
+- Tests for periodic logging (mock time)
+- Optional: Tests for Telegram command flow