1m-handshake 0.1.0__tar.gz

1m_handshake-0.1.0/1m_handshake.egg-info/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: 1m-handshake
+Version: 0.1.0
+Summary: Client-side addon for creating verified 1M Agent Handshake registry claims
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: a2a-sdk<2,>=1.1
+Requires-Dist: azure-identity<2,>=1.19
+Requires-Dist: click<9,>=8.1
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: x402[evm]<3,>=2.18
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Dynamic: license-file
+
+# 1M Handshake Addon
+
+The free client-side addon for the 1M Agent Handshake registry. It connects your organization's A2A-capable agent to the registry and supplies proof when your agent makes a real call to another organization's public AgentCard.
+
+Installing and using the addon is free. A fee is charged only when a credit is redeemed to create a permanent, public handshake record in the registry.
+
+## Install
+
+```sh
+pip install 1m-handshake
+```
+
+## Set up your organization
+
+Run the install command once for your organization. Supply the public 1M Handshake service URL provided for your environment:
+
+```sh
+1m-handshake install \
+  --org-domain acme.example \
+  --backend-url https://<1m-handshake-service-url>
+```
+
+The addon first tries a configured enterprise agent identity. If that is unavailable, it guides you through one-time work-email or DNS-TXT domain verification.
+
+## Create a handshake
+
+After a credit has been purchased for a selected counterparty, redeem it by having your agent make a real A2A call:
+
+```sh
+1m-handshake on-demand <credit-code>
+```
+
+You can also use an eligible prepaid credit for a chosen organization:
+
+```sh
+1m-handshake use-credit counterparty.example
+```
+
+The addon never stores wallet or payment-provider credentials. Autonomous x402 redemption is opt-in and requires a signer supplied by the host integration.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

1m_handshake-0.1.0/1m_handshake.egg-info/SOURCES.txt

@@ -0,0 +1,39 @@
+LICENSE
+README.md
+pyproject.toml
+1m_handshake.egg-info/PKG-INFO
+1m_handshake.egg-info/SOURCES.txt
+1m_handshake.egg-info/dependency_links.txt
+1m_handshake.egg-info/entry_points.txt
+1m_handshake.egg-info/requires.txt
+1m_handshake.egg-info/top_level.txt
+handshake_addon/__init__.py
+handshake_addon/a2a_dispatch.py
+handshake_addon/autonomous.py
+handshake_addon/backend_client.py
+handshake_addon/cli.py
+handshake_addon/confirmation.py
+handshake_addon/idp_discovery.py
+handshake_addon/local_store.py
+handshake_addon/on_demand.py
+handshake_addon/reactive.py
+handshake_addon/staging_x402_signer.py
+handshake_addon/use_credit.py
+handshake_addon/verification.py
+handshake_addon/x402_client.py
+tests/test_a2a_dispatch.py
+tests/test_autonomous.py
+tests/test_backend_client.py
+tests/test_cli_autonomy.py
+tests/test_cli_install.py
+tests/test_cli_on_demand.py
+tests/test_cli_use_credit.py
+tests/test_confirmation.py
+tests/test_idp_discovery.py
+tests/test_local_store.py
+tests/test_on_demand.py
+tests/test_reactive.py
+tests/test_staging_x402_signer.py
+tests/test_use_credit.py
+tests/test_verification.py
+tests/test_x402_client.py

1m_handshake-0.1.0/1m_handshake.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

1m_handshake-0.1.0/1m_handshake.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+1m-handshake = handshake_addon.cli:cli

1m_handshake-0.1.0/1m_handshake.egg-info/requires.txt

@@ -0,0 +1,10 @@
+a2a-sdk<2,>=1.1
+azure-identity<2,>=1.19
+click<9,>=8.1
+httpx<1,>=0.27
+x402[evm]<3,>=2.18
+
+[dev]
+pytest>=8.3
+pytest-asyncio>=0.24
+respx>=0.21

1m_handshake-0.1.0/1m_handshake.egg-info/top_level.txt

@@ -0,0 +1 @@
+handshake_addon

1m_handshake-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Freshstart Digital
+
+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.

1m_handshake-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: 1m-handshake
+Version: 0.1.0
+Summary: Client-side addon for creating verified 1M Agent Handshake registry claims
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: a2a-sdk<2,>=1.1
+Requires-Dist: azure-identity<2,>=1.19
+Requires-Dist: click<9,>=8.1
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: x402[evm]<3,>=2.18
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Dynamic: license-file
+
+# 1M Handshake Addon
+
+The free client-side addon for the 1M Agent Handshake registry. It connects your organization's A2A-capable agent to the registry and supplies proof when your agent makes a real call to another organization's public AgentCard.
+
+Installing and using the addon is free. A fee is charged only when a credit is redeemed to create a permanent, public handshake record in the registry.
+
+## Install
+
+```sh
+pip install 1m-handshake
+```
+
+## Set up your organization
+
+Run the install command once for your organization. Supply the public 1M Handshake service URL provided for your environment:
+
+```sh
+1m-handshake install \
+  --org-domain acme.example \
+  --backend-url https://<1m-handshake-service-url>
+```
+
+The addon first tries a configured enterprise agent identity. If that is unavailable, it guides you through one-time work-email or DNS-TXT domain verification.
+
+## Create a handshake
+
+After a credit has been purchased for a selected counterparty, redeem it by having your agent make a real A2A call:
+
+```sh
+1m-handshake on-demand <credit-code>
+```
+
+You can also use an eligible prepaid credit for a chosen organization:
+
+```sh
+1m-handshake use-credit counterparty.example
+```
+
+The addon never stores wallet or payment-provider credentials. Autonomous x402 redemption is opt-in and requires a signer supplied by the host integration.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

1m_handshake-0.1.0/README.md

@@ -0,0 +1,43 @@
+# 1M Handshake Addon
+
+The free client-side addon for the 1M Agent Handshake registry. It connects your organization's A2A-capable agent to the registry and supplies proof when your agent makes a real call to another organization's public AgentCard.
+
+Installing and using the addon is free. A fee is charged only when a credit is redeemed to create a permanent, public handshake record in the registry.
+
+## Install
+
+```sh
+pip install 1m-handshake
+```
+
+## Set up your organization
+
+Run the install command once for your organization. Supply the public 1M Handshake service URL provided for your environment:
+
+```sh
+1m-handshake install \
+  --org-domain acme.example \
+  --backend-url https://<1m-handshake-service-url>
+```
+
+The addon first tries a configured enterprise agent identity. If that is unavailable, it guides you through one-time work-email or DNS-TXT domain verification.
+
+## Create a handshake
+
+After a credit has been purchased for a selected counterparty, redeem it by having your agent make a real A2A call:
+
+```sh
+1m-handshake on-demand <credit-code>
+```
+
+You can also use an eligible prepaid credit for a chosen organization:
+
+```sh
+1m-handshake use-credit counterparty.example
+```
+
+The addon never stores wallet or payment-provider credentials. Autonomous x402 redemption is opt-in and requires a signer supplied by the host integration.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

1m_handshake-0.1.0/handshake_addon/a2a_dispatch.py

@@ -0,0 +1,94 @@
+# handshake_addon/a2a_dispatch.py
+"""On-demand mode's active call origination.
+
+Unlike reactive mode (a separate, later plan), which only *observes* calls
+an org's own agent already made via an SDK interceptor, on-demand mode
+requires the addon itself to *originate* a real SendMessage call — the
+owner explicitly paid for this specific call to happen right now.
+
+The A2A SDK's message-sending surface is protobuf-based, confirmed against
+the actually-installed a2a-sdk==1.1.2 (not assumed): `ClientFactory` /
+`ClientConfig` come from `a2a.client`; `Message`/`Part`/`Role`/
+`SendMessageRequest`/`StreamResponse`/`Task`/`TaskStatus`/`TaskState` come
+from `a2a.types.a2a_pb2`. `ClientFactory(config).create_from_url(url)`
+fetches `<url>/.well-known/agent-card.json` automatically.
+"""
+import uuid
+from datetime import datetime, timezone
+
+import httpx
+from a2a.client import ClientConfig, ClientFactory
+from a2a.types.a2a_pb2 import Message, Part, Role, SendMessageRequest, TaskState
+
+
+class DispatchFailed(Exception):
+    """The addon could not complete a real SendMessage call to the counterparty."""
+
+
+_FAILURE_STATES = {"failed", "rejected", "canceled", "unspecified", "unknown"}
+
+
+def _task_status_from_response(response) -> str | None:
+    """Returns the task's state if this response carries one, else None.
+
+    `message`/`artifact_update` events (and an unset oneof) carry no task
+    state — they must not overwrite a real terminal state seen earlier in
+    the stream, and must not be reported as a task outcome themselves.
+    """
+    which = response.WhichOneof("payload")
+    if which == "task":
+        return TaskState.Name(response.task.status.state).removeprefix("TASK_STATE_").lower()
+    if which == "status_update":
+        return TaskState.Name(response.status_update.status.state).removeprefix("TASK_STATE_").lower()
+    return None
+
+
+async def dispatch_call(org_b_domain: str) -> dict:
+    """Actively originates a real A2A SendMessage call to org_b_domain.
+
+    Returns a dict matching the backend's CallProof schema (method,
+    target_domain, status, timestamp) built from what actually happened —
+    never fabricated, never assumed successful. Raises DispatchFailed for
+    any failure: unreachable AgentCard, a failed send, or no response at
+    all.
+    """
+    async with httpx.AsyncClient(timeout=15.0) as http_client:
+        factory = ClientFactory(ClientConfig(httpx_client=http_client, streaming=False))
+        try:
+            client = await factory.create_from_url(f"https://{org_b_domain}")
+        except Exception as e:
+            raise DispatchFailed(f"could not resolve {org_b_domain}'s AgentCard: {e}") from e
+
+        request = SendMessageRequest(
+            message=Message(
+                message_id=str(uuid.uuid4()),
+                role=Role.ROLE_USER,
+                parts=[Part(text="1M Agent Handshake — on-demand verification call.")],
+            )
+        )
+        last_response = None
+        last_task_status = None
+        try:
+            async for response in client.send_message(request):
+                last_response = response
+                status = _task_status_from_response(response)
+                if status is not None:
+                    last_task_status = status
+        except Exception as e:
+            raise DispatchFailed(f"SendMessage call to {org_b_domain} failed: {e}") from e
+        finally:
+            await client.close()
+
+    if last_response is None:
+        raise DispatchFailed(f"{org_b_domain} returned no response to the SendMessage call")
+
+    status = last_task_status if last_task_status is not None else "unknown"
+    if status in _FAILURE_STATES:
+        raise DispatchFailed(f"{org_b_domain} reported the call did not complete (status={status!r})")
+
+    return {
+        "method": "send_message",
+        "target_domain": org_b_domain,
+        "status": status,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }

1m_handshake-0.1.0/handshake_addon/autonomous.py

@@ -0,0 +1,80 @@
+"""Bounded, recoverable autonomous x402 claims for observed reactive proofs."""
+import json
+import uuid
+from datetime import datetime, timezone
+from dataclasses import dataclass
+
+from x402.schemas import PaymentRequired
+
+from handshake_addon import backend_client
+from handshake_addon.local_store import LocalStore
+from handshake_addon.x402_client import PaymentSignerProvider, SignerUnavailable, create_payment_payload
+
+
+def _key(org_b: str, org_a: str) -> str:
+    return f"autonomous_charge:{org_b}:{org_a}"
+
+
+def policy_key(org_a: str) -> str:
+    return f"autonomy_policy:{org_a}"
+
+
+def get_policy(store: LocalStore, org_a: str) -> dict | None:
+    raw = store.get(policy_key(org_a))
+    try:
+        return json.loads(raw) if raw else None
+    except json.JSONDecodeError:
+        return None
+
+
+@dataclass
+class AutonomousResult:
+    status: str  # succeeded | pending | unavailable | failed
+    message: str
+
+
+async def attempt_claim(*, backend_base_url: str, org_a_domain: str, org_b_domain: str,
+                        description: str, proof: dict, store: LocalStore,
+                        signer_provider: PaymentSignerProvider | None) -> AutonomousResult:
+    policy = get_policy(store, org_a_domain)
+    if policy is None or signer_provider is None:
+        return AutonomousResult("unavailable", "")
+    key = _key(org_b_domain, org_a_domain)
+    prior_raw = store.get(key)
+    if prior_raw:
+        try:
+            prior = json.loads(prior_raw)
+            attempt_id = prior.get("attempt_id")
+            if attempt_id:
+                info = await backend_client.get_checkout_attempt(backend_base_url, attempt_id)
+                if info.status == "settled" and info.approval_code:
+                    result = await backend_client.redeem_code(backend_base_url, info.approval_code.code, proof)
+                    prior.update(status="succeeded", code=info.approval_code.code)
+                    store.set(key, json.dumps(prior))
+                    return AutonomousResult("succeeded", f"I already claimed this interaction as handshake #{result.sequence_number}.")
+                if info.status == "settling":
+                    return AutonomousResult("pending", "I'm handling this handshake; check back shortly.")
+        except Exception:
+            return AutonomousResult("pending", "I'm handling this handshake; check back shortly.")
+    attempt_id = str(uuid.uuid4())
+    audit = {"status": "attempted", "attempt_id": attempt_id, "timestamp": datetime.now(timezone.utc).isoformat()}
+    store.set(key, json.dumps(audit))
+    request = {"org_a_domain": org_a_domain, "org_b_domain": org_b_domain, "description": description, "trigger_mode": "reactive"}
+    try:
+        challenge = await backend_client.start_x402_checkout(backend_base_url, request, attempt_id)
+        if challenge.amount_cents > int(policy["max_cents"]):
+            audit.update(status="failed", amount_cents=challenge.amount_cents)
+            store.set(key, json.dumps(audit))
+            return AutonomousResult("failed", "")
+        payload = await create_payment_payload(PaymentRequired.model_validate(challenge.x402_requirements), signer_provider)
+        info = await backend_client.submit_x402_payment(backend_base_url, request, attempt_id, payload)
+        if info.status != "settled" or not info.approval_code:
+            return AutonomousResult("pending", "I'm handling this handshake; check back shortly.")
+        result = await backend_client.redeem_code(backend_base_url, info.approval_code.code, proof)
+        audit.update(status="succeeded", amount_cents=challenge.amount_cents, code=info.approval_code.code)
+        store.set(key, json.dumps(audit))
+        return AutonomousResult("succeeded", f"I already claimed this interaction as handshake #{result.sequence_number}.")
+    except SignerUnavailable:
+        return AutonomousResult("unavailable", "")
+    except Exception:
+        return AutonomousResult("pending", "I'm handling this handshake; check back shortly.")