theprotocol-sdk 0.2.0__tar.gz → 0.5.1__tar.gz

theprotocol_sdk-0.5.1/.gitignore

@@ -0,0 +1,59 @@
+# TheProtocol — Root .gitignore
+# Created: 2026-03-09 (§4.1 Credentials Rotation)
+
+# !! NEVER COMMIT SECRETS / LOCAL CONFIG !!
+# All env files except *.example templates. Covers .env, .env.production,
+# .env.frame-b, .env.frame-c, .env.operator, .env.docker, and nested
+# AgentVault/.../.env — while keeping the committed *.env.example templates.
+.env
+.env.*
+!.env.example
+# Local agent / MCP config — these carry live API keys
+.mcp.json
+.claude/
+
+# Session logs (operational, not source)
+sessionlogs2026/
+
+# Debug/runtime artifacts
+logs/
+*.log
+APEX_PREDATOR_JOBS.log
+
+# Node
+node_modules/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.venv/
+*.egg-info/
+dist/
+build/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Backups / snapshots — carry stale secrets + bloat
+# (e.g. *.bak-pre-*, PRODUCTION_DOCS.bak-*, CLAUDE.md.bak-*, main.py.bak-*)
+*.bak*
+*.pre-*
+
+# §2026-06-29 OSS secrets scrub (#153) — internal AI-operational docs + credential
+# references that carry live secrets and MUST NOT ship to a public repo. These are
+# operator/agent briefings, not platform source.
+CLAUDE.md
+CLAUDE_ADMIN.md
+MY_APEX_PREDATOR_TOOLING.md
+PRODUCTION_DOCS/CREDENTIALS_REFERENCE.md
+# Sim/dev credential blobs
+scripts/sim_credentials.json
+**/*credentials*.json
+
+# Throwaway FE screenshot/diag scripts (scratch, carry prod creds)
+AgentVault/agentvault_registry/src/agentvault_registry/static/new_registry_frontend/shot_*.mjs
+AgentVault/agentvault_registry/src/agentvault_registry/static/new_registry_frontend/diag_*.mjs
+AgentVault/agentvault_registry/src/agentvault_registry/static/new_registry_frontend/gate_*.mjs

{theprotocol_sdk-0.2.0 → theprotocol_sdk-0.5.1}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: theprotocol-sdk
-Version: 0.2.0
-Summary: TheProtocol SDK — Build and call A2A agents. Protocol bridges for ACP, ADK, and more.
+Version: 0.5.1
+Summary: A2A v1.0 SDK — Build sovereign AI agents with DID identity. Protocol bridges for Google A2A, ANP, MCP. Works with Vertex AI, AWS AgentCore, LangGraph, CrewAI.
 Project-URL: Homepage, https://theprotocol.cloud
 Project-URL: Documentation, https://api.theprotocol.cloud/docs
 Project-URL: Repository, https://github.com/theprotocol/theprotocol-sdk
 Author-email: TheProtocol <sdk@theprotocol.cloud>
 License: Apache-2.0
 License-File: LICENSE
-Keywords: a2a,agents,ai,mcp,protocol,theprotocol
+Keywords: a2a,a2a-protocol,agent-to-agent,agents,ai-agents,crewai,did,fastapi,federation,json-rpc,langchain,mcp,sovereign,theprotocol,vertex-ai
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
@@ -127,6 +127,72 @@ Any platform that speaks A2A v1.0 can call your agent directly:
 
 No additional bridges needed. The SDK's JSON-RPC endpoint is the universal interface.
 
+## Smart Send (one call, any destination) — new in 0.5.0
+
+The registry auto-routes value movement: local / cross-registry 2PC / async / cross-frame FX (AVT↔BVT) — derived from the federated agent-card cache. You never pick an endpoint.
+
+```python
+from theprotocol.transfer import TransferClient
+
+client = TransferClient("https://api.theprotocol.cloud")
+plan = await client.preview(agent_jwt, "did:theprotocol:receiver", "2.5")
+print(plan["method"], plan["currency_sent"], "->", plan["currency_received"])
+
+result = await client.send(agent_jwt, "did:theprotocol:receiver", "2.5",
+                           message="invoice 42", idempotency_key="inv-42")
+print(result["status"], result["transfer_id"])
+```
+
+`backend="async"` opts a same-currency remote transfer into the locked→settled rail; FX and local routes are decided by the registry. Non-2xx raises `SmartSendError` with the registry's status code and structured detail.
+
+## Changelog
+
+**0.5.1** (2026-07-09)
+- FastAPI ≥ 0.139 / Starlette 1.x compatibility: `serve_well_known_card` federated mode no longer relies on the removed `add_event_handler` API — startup registration now degrades gracefully (`add_event_handler` → `router.on_startup` → lifespan-context wrap). Verified 173/173 tests on both fastapi 0.111 (floor) and 0.139.
+
+**0.5.0** (2026-06-12)
+- NEW `theprotocol.transfer.TransferClient` — unified smart send (`POST /api/v1/teg/send`): auto-routed local / 2PC / async / cross-frame FX, `preview()` dry-runs, idempotency-key passthrough, `SmartSendError`.
+- `PaymentVerifier(reject_reused_tokens=True)` — opt-in single-acceptance enforcement per process (P25-001 refinement). Default behavior unchanged (registry verify-on-CONSUMED stays valid for delivery retries).
+- A2A v1.0 surface from the 2026-05-12 migration ships in this version: unified `A2AAuthenticator` (mTLS → agent-JWT → payment fanout), `theprotocol.auth.did_jwt` EdDSA helpers, v1.0-native `AgentCard` with dual-shape compatibility, Part `kind` discriminators.
+
+## Payment & mTLS Authentication
+
+Enforce payment on your agent's A2A endpoints and authenticate callers via SPIFFE mTLS:
+
+```python
+# Agent side — require payment tokens on all A2A calls
+from theprotocol.payment import PaymentVerifier
+from theprotocol.agent import create_a2a_router
+from fastapi import Depends
+
+verifier = PaymentVerifier(
+    registry_url="https://api.theprotocol.cloud",
+    agent_did="did:theprotocol:my-agent",
+)
+router = create_a2a_router(my_agent, dependencies=[Depends(verifier)])
+```
+
+```python
+# Caller side — acquire payment token before calling an agent
+from theprotocol.payment import PaymentClient
+
+client = PaymentClient("https://api.theprotocol.cloud")
+token = await client.get_token(agent_jwt, target_did="...", amount="0.5")
+headers = {"X-Payment-Token": token}
+```
+
+```python
+# mTLS — authenticate agent-to-agent calls with SPIFFE SVIDs
+from theprotocol.payment import A2AAuthenticator, MtlsAgentClient
+
+# Verify incoming mTLS + payment tokens (hybrid auth)
+auth = A2AAuthenticator(registry_url="https://api.theprotocol.cloud")
+
+# Make outbound mTLS calls using your agent's SVID
+client = MtlsAgentClient(cert_dir="/certs")
+result = await client.call(target_url, payload)
+```
+
 ## MCP Tools
 
 For governance, staking, transfers, and discovery — use [MCP tools](https://api.theprotocol.cloud/mcp/sse) (19 tools via Claude Desktop or any MCP client).

theprotocol_sdk-0.5.1/README.md

@@ -0,0 +1,161 @@
+# theprotocol-sdk
+
+**A2A v1.0** — Build and call AI agents on [TheProtocol](https://theprotocol.cloud). Native protocol bridges for Google A2A, ANP, and MCP.
+
+## Install
+
+```bash
+pip install theprotocol-sdk              # Client only (call agents)
+pip install theprotocol-sdk[server]      # + FastAPI router (build agents)
+pip install theprotocol-sdk[anp]         # + Ed25519 crypto for ANP DID:WBA
+pip install theprotocol-sdk[all]         # Everything
+```
+
+## Build an Agent
+
+```python
+from theprotocol.agent import BaseA2AAgent, create_a2a_router
+from fastapi import FastAPI
+
+class MyAgent(BaseA2AAgent):
+    async def handle_task_send(self, task_id, message):
+        return "task-1"
+    async def handle_task_get(self, task_id): ...
+    async def handle_task_cancel(self, task_id): return True
+    async def handle_subscribe_request(self, task_id): yield
+
+app = FastAPI()
+app.include_router(create_a2a_router(MyAgent()))
+```
+
+Your agent speaks A2A v1.0 out of the box. It accepts both `message/send` (v1.0) and `tasks/send` (v0.3) for backward compatibility.
+
+## Call a Remote Agent
+
+```python
+from theprotocol.client import A2AClient, KeyManager
+from theprotocol.models import Message, TextPart
+
+async with A2AClient() as client:
+    task_id = await client.initiate_task(agent_card, message, key_manager)
+    task = await client.get_task_status(agent_card, task_id, key_manager)
+    print(task.state)  # TASK_STATE_COMPLETED
+```
+
+The client sends v1.0 wire format and accepts responses from both v1.0 and v0.3 agents.
+
+## Dockerize
+
+```dockerfile
+FROM python:3.11-slim
+WORKDIR /app
+RUN pip install --no-cache-dir theprotocol-sdk[server] uvicorn
+COPY agent.py .
+EXPOSE 9500
+CMD ["uvicorn", "agent:app", "--host", "0.0.0.0", "--port", "9500"]
+```
+
+Register on TheProtocol and your agent gets a permanent DID, OAuth credentials, and a 1,000 AVT genesis grant.
+
+## Protocol Bridges
+
+Translate between A2A and other agent protocols:
+
+| Bridge | Protocol | Use Case |
+|--------|----------|----------|
+| `GoogleA2ABridge` | Google A2A REST | Expose agents via REST binding (Vertex AI, AgentCore) |
+| `ANPBridge` | Agent Network Protocol | DID:WBA identity linking, Ed25519 auth |
+| `MCPBridge` | Model Context Protocol | Expose agents as MCP tool servers |
+| `ACPBridge` | ACP (deprecated) | Legacy BeeAI compat — use GoogleA2ABridge instead |
+
+```python
+from theprotocol.bridges.google_a2a import GoogleA2ABridge
+from theprotocol.bridges.anp import ANPBridge
+from theprotocol.bridges.mcp import MCPBridge
+```
+
+## Platform Compatibility
+
+Any platform that speaks A2A v1.0 can call your agent directly:
+
+- **Google Vertex AI** — native A2A support
+- **AWS Bedrock AgentCore** — native A2A support
+- **LangGraph Cloud** — native A2A support
+- **CrewAI** — native A2A support
+- **Azure AI Foundry** — A2A in preview
+
+No additional bridges needed. The SDK's JSON-RPC endpoint is the universal interface.
+
+## Smart Send (one call, any destination) — new in 0.5.0
+
+The registry auto-routes value movement: local / cross-registry 2PC / async / cross-frame FX (AVT↔BVT) — derived from the federated agent-card cache. You never pick an endpoint.
+
+```python
+from theprotocol.transfer import TransferClient
+
+client = TransferClient("https://api.theprotocol.cloud")
+plan = await client.preview(agent_jwt, "did:theprotocol:receiver", "2.5")
+print(plan["method"], plan["currency_sent"], "->", plan["currency_received"])
+
+result = await client.send(agent_jwt, "did:theprotocol:receiver", "2.5",
+                           message="invoice 42", idempotency_key="inv-42")
+print(result["status"], result["transfer_id"])
+```
+
+`backend="async"` opts a same-currency remote transfer into the locked→settled rail; FX and local routes are decided by the registry. Non-2xx raises `SmartSendError` with the registry's status code and structured detail.
+
+## Changelog
+
+**0.5.1** (2026-07-09)
+- FastAPI ≥ 0.139 / Starlette 1.x compatibility: `serve_well_known_card` federated mode no longer relies on the removed `add_event_handler` API — startup registration now degrades gracefully (`add_event_handler` → `router.on_startup` → lifespan-context wrap). Verified 173/173 tests on both fastapi 0.111 (floor) and 0.139.
+
+**0.5.0** (2026-06-12)
+- NEW `theprotocol.transfer.TransferClient` — unified smart send (`POST /api/v1/teg/send`): auto-routed local / 2PC / async / cross-frame FX, `preview()` dry-runs, idempotency-key passthrough, `SmartSendError`.
+- `PaymentVerifier(reject_reused_tokens=True)` — opt-in single-acceptance enforcement per process (P25-001 refinement). Default behavior unchanged (registry verify-on-CONSUMED stays valid for delivery retries).
+- A2A v1.0 surface from the 2026-05-12 migration ships in this version: unified `A2AAuthenticator` (mTLS → agent-JWT → payment fanout), `theprotocol.auth.did_jwt` EdDSA helpers, v1.0-native `AgentCard` with dual-shape compatibility, Part `kind` discriminators.
+
+## Payment & mTLS Authentication
+
+Enforce payment on your agent's A2A endpoints and authenticate callers via SPIFFE mTLS:
+
+```python
+# Agent side — require payment tokens on all A2A calls
+from theprotocol.payment import PaymentVerifier
+from theprotocol.agent import create_a2a_router
+from fastapi import Depends
+
+verifier = PaymentVerifier(
+    registry_url="https://api.theprotocol.cloud",
+    agent_did="did:theprotocol:my-agent",
+)
+router = create_a2a_router(my_agent, dependencies=[Depends(verifier)])
+```
+
+```python
+# Caller side — acquire payment token before calling an agent
+from theprotocol.payment import PaymentClient
+
+client = PaymentClient("https://api.theprotocol.cloud")
+token = await client.get_token(agent_jwt, target_did="...", amount="0.5")
+headers = {"X-Payment-Token": token}
+```
+
+```python
+# mTLS — authenticate agent-to-agent calls with SPIFFE SVIDs
+from theprotocol.payment import A2AAuthenticator, MtlsAgentClient
+
+# Verify incoming mTLS + payment tokens (hybrid auth)
+auth = A2AAuthenticator(registry_url="https://api.theprotocol.cloud")
+
+# Make outbound mTLS calls using your agent's SVID
+client = MtlsAgentClient(cert_dir="/certs")
+result = await client.call(target_url, payload)
+```
+
+## MCP Tools
+
+For governance, staking, transfers, and discovery — use [MCP tools](https://api.theprotocol.cloud/mcp/sse) (19 tools via Claude Desktop or any MCP client).
+
+## License
+
+Apache-2.0

{theprotocol_sdk-0.2.0 → theprotocol_sdk-0.5.1}/pyproject.toml

@@ -4,15 +4,15 @@ build-backend = "hatchling.build"
 
 [project]
 name = "theprotocol-sdk"
-version = "0.2.0"
-description = "TheProtocol SDK — Build and call A2A agents. Protocol bridges for ACP, ADK, and more."
+version = "0.5.1"
+description = "A2A v1.0 SDK — Build sovereign AI agents with DID identity. Protocol bridges for Google A2A, ANP, MCP. Works with Vertex AI, AWS AgentCore, LangGraph, CrewAI."
 readme = "README.md"
 license = {text = "Apache-2.0"}
 requires-python = ">=3.10"
 authors = [
     {name = "TheProtocol", email = "sdk@theprotocol.cloud"},
 ]
-keywords = ["agents", "a2a", "protocol", "ai", "mcp", "theprotocol"]
+keywords = ["agents", "a2a", "a2a-protocol", "agent-to-agent", "ai-agents", "mcp", "did", "sovereign", "federation", "vertex-ai", "langchain", "crewai", "fastapi", "json-rpc", "theprotocol"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",

{theprotocol_sdk-0.2.0 → theprotocol_sdk-0.5.1}/src/theprotocol/__init__.py

@@ -5,6 +5,7 @@ Usage:
     from theprotocol.models import Message, Task, AgentCard
     from theprotocol.agent import BaseA2AAgent, create_a2a_router
     from theprotocol.client import A2AClient, KeyManager
+    from theprotocol.transfer import TransferClient   # smart send (auto-routed value movement)
 """
 
-__version__ = "0.1.0"
+__version__ = "0.5.1"

{theprotocol_sdk-0.2.0 → theprotocol_sdk-0.5.1}/src/theprotocol/agent/__init__.py

@@ -15,3 +15,10 @@ try:
     __all__.append("create_a2a_router")
 except ImportError:
     pass
+
+# A2A v1.0 §4.1.2 well-known discovery — also requires fastapi.
+try:
+    from .well_known import serve_well_known_card
+    __all__.append("serve_well_known_card")
+except ImportError:
+    pass

{theprotocol_sdk-0.2.0 → theprotocol_sdk-0.5.1}/src/theprotocol/agent/router.py

@@ -1,9 +1,21 @@
 """FastAPI router factory for A2A agents.
-Accepts both A2A v1.0 and v0.3 wire formats. Responds in v1.0."""
+Accepts both A2A v1.0 and v0.3 wire formats. Responds in v1.0.
+
+Payment enforcement (f045):
+  When REGISTRY_URL env var is set, a PaymentVerifier is automatically
+  injected into the router dependencies. This means every SDK-based agent
+  gets payment verification by default when deployed to the network.
+
+  - REGISTRY_URL set → payment verification ON (required=True by default)
+  - PAYMENT_REQUIRED=false → verification runs but doesn't reject (log only)
+  - REGISTRY_URL not set → no verification (dev/testing mode)
+  - Price=0 agents: caller still gets a 0 AVT token (proves identity), no funds move
+"""
 
 import json
 import inspect
 import logging
+import os
 from typing import Any, Dict, Optional, Union, List, Callable, AsyncGenerator
 
 import pydantic
@@ -87,10 +99,19 @@ def create_a2a_router(
     tags: Optional[List[str]] = None,
     task_store: Optional[BaseTaskStore] = None,
     dependencies: Optional[list] = None,
+    payment_required: Optional[bool] = None,
 ) -> APIRouter:
     """
     Create a FastAPI router that exposes an A2A agent via JSON-RPC 2.0.
 
+    Payment enforcement is automatic when REGISTRY_URL env var is set:
+    - REGISTRY_URL → PaymentVerifier injected (agents must receive payment tokens)
+    - AGENT_DID → identifies this agent for token target validation
+    - PAYMENT_REQUIRED=false → verify but don't reject (log only mode)
+    - TRUSTED_REGISTRIES → comma-separated URLs for cross-registry tokens
+
+    Override with payment_required=False to explicitly disable.
+
     Example::
 
         from theprotocol.agent import BaseA2AAgent, create_a2a_router
@@ -102,7 +123,11 @@ def create_a2a_router(
             ...
 
         app = FastAPI()
+        # Payment verification is automatic if REGISTRY_URL is set
         app.include_router(create_a2a_router(MyAgent()))
+
+        # Explicitly disable payment verification
+        app.include_router(create_a2a_router(MyAgent(), payment_required=False))
     """
     if tags is None:
         tags = ["A2A Protocol"]
@@ -110,7 +135,60 @@ def create_a2a_router(
         task_store = InMemoryTaskStore()
     store = task_store
 
-    router = APIRouter(prefix=prefix, tags=tags, dependencies=dependencies or [])
+    # Build dependencies list
+    all_deps = list(dependencies or [])
+
+    # Auto-inject PaymentVerifier if REGISTRY_URL is configured
+    _registry_url = os.environ.get("REGISTRY_URL", "")
+    _agent_did = os.environ.get("AGENT_DID", "")
+    _pay_required = payment_required
+    if _pay_required is None:
+        _pay_required = os.environ.get("PAYMENT_REQUIRED", "true").lower() != "false"
+
+    if _registry_url and _agent_did and _pay_required is not False:
+        try:
+            from ..payment.verifier import PaymentVerifier
+            _trusted_raw = os.environ.get("TRUSTED_REGISTRIES", "")
+            _trusted = [u.strip() for u in _trusted_raw.split(",") if u.strip()] if _trusted_raw else None
+            _verifier = PaymentVerifier(
+                registry_url=_registry_url,
+                agent_did=_agent_did,
+                required=bool(_pay_required),
+                trusted_registries=_trusted,
+            )
+            all_deps.append(Depends(_verifier))
+            logger.info(
+                f"[A2A Router] PaymentVerifier auto-injected "
+                f"(registry={_registry_url}, did={_agent_did[:30]}, required={_pay_required})"
+            )
+        except ImportError:
+            logger.warning("[A2A Router] PaymentVerifier import failed — payment module not installed")
+        except Exception as e:
+            logger.warning(f"[A2A Router] PaymentVerifier setup failed: {e}")
+    elif _registry_url and not _agent_did:
+        logger.warning("[A2A Router] REGISTRY_URL set but AGENT_DID missing — payment verification disabled")
+
+    # f052: Auto-inject A2AAuthenticator if SPIRE socket is available (IRONHAND)
+    _spiffe_socket = os.environ.get("SPIFFE_ENDPOINT_SOCKET", "")
+    _enable_mtls = os.environ.get("ENABLE_MTLS", "").lower() == "true"
+    if _spiffe_socket and _enable_mtls:
+        try:
+            from ..payment.authenticator import A2AAuthenticator
+            _authenticator = A2AAuthenticator(
+                payment_verifier=_verifier if "_verifier" in dir() else None,
+                required=False,
+            )
+            all_deps.append(Depends(_authenticator))
+            logger.info(
+                f"[A2A Router] A2AAuthenticator auto-injected (mTLS enabled, "
+                f"socket={_spiffe_socket[:40]})"
+            )
+        except ImportError:
+            logger.warning("[A2A Router] A2AAuthenticator import failed — mTLS module not installed")
+        except Exception as e:
+            logger.warning(f"[A2A Router] A2AAuthenticator setup failed: {e}")
+
+    router = APIRouter(prefix=prefix, tags=tags, dependencies=all_deps)
 
     # Discover @a2a_method decorated handlers
     decorated: Dict[str, Callable] = {}
@@ -118,6 +196,9 @@ def create_a2a_router(
         if hasattr(method, '_a2a_method_name'):
             decorated[getattr(method, '_a2a_method_name')] = method
 
+    # Register on both the bare prefix and the trailing slash so `POST /a2a`
+    # works without a 307 redirect (which drops the POST body for many clients).
+    @router.post("", summary="A2A JSON-RPC Endpoint", include_in_schema=False)
     @router.post("/", summary="A2A JSON-RPC Endpoint")
     async def handle_request(request: Request) -> Response:
         req_id = None

{theprotocol_sdk-0.2.0 → theprotocol_sdk-0.5.1}/src/theprotocol/agent/task_store.py

@@ -101,7 +101,13 @@ class BaseTaskStore(ABC):
 
 
 class InMemoryTaskStore(BaseTaskStore):
-    """In-memory task store. Suitable for development and single-process agents."""
+    """In-memory task store. Suitable for development and single-process agents.
+
+    Bounded: keeps at most ``_MAX_TASKS`` tasks, evicting oldest-first (FIFO) on
+    insert so long-running agents don't leak memory over time.
+    """
+
+    _MAX_TASKS = 2000
 
     def __init__(self):
         self._tasks: Dict[str, TaskContext] = {}
@@ -119,6 +125,13 @@ class InMemoryTaskStore(BaseTaskStore):
             ctx = TaskContext(task_id=task_id, current_state=TaskState.SUBMITTED)
             self._tasks[task_id] = ctx
             self._listeners[task_id] = []
+            # Bounded GC: evict oldest entries (FIFO) to cap memory.
+            while len(self._tasks) > self._MAX_TASKS:
+                old_id = next(iter(self._tasks))
+                if old_id == task_id:
+                    break
+                self._tasks.pop(old_id, None)
+                self._listeners.pop(old_id, None)
         await self.notify_status_update(task_id, TaskState.SUBMITTED)
         return ctx