theprotocol-sdk 0.6.1__tar.gz → 0.7.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/.gitignore +7 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/PKG-INFO +24 -1
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/README.md +23 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/pyproject.toml +8 -1
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/__init__.py +3 -1
- theprotocol_sdk-0.7.0/src/theprotocol/messenger.py +256 -0
- theprotocol_sdk-0.7.0/src/theprotocol/mtls.py +337 -0
- theprotocol_sdk-0.7.0/tests/test_messenger.py +208 -0
- theprotocol_sdk-0.7.0/tests/test_mtls_enroll.py +270 -0
- theprotocol_sdk-0.6.1/dist_release/theprotocol_sdk-0.5.1-py3-none-any.whl +0 -0
- theprotocol_sdk-0.6.1/dist_release/theprotocol_sdk-0.5.1.tar.gz +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/LICENSE +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/examples/simple_agent.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/agent/__init__.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/agent/base.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/agent/decorators.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/agent/router.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/agent/task_store.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/agent/well_known.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/auth/__init__.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/auth/did_jwt.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/auth/jws_card.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/auth/jwt_verifier.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/authz.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/bridges/__init__.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/bridges/acp.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/bridges/anp/__init__.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/bridges/anp/auth.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/bridges/anp/bridge.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/bridges/anp/did_wba.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/bridges/anp/translation.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/bridges/base.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/bridges/google_a2a.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/bridges/mcp.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/client/__init__.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/client/a2a_client.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/client/credentials.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/exceptions.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/exchange/__init__.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/exchange/client.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/forge.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/guild.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/models/__init__.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/models/a2a_protocol.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/models/agent_card.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/models/v1_compat.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/payment/__init__.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/payment/authenticator.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/payment/client.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/payment/mtls_client.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/payment/verifier.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/registry/__init__.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/registry/card_verify.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/registry/cost_composition.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/transfer/__init__.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/src/theprotocol/transfer/client.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/tests/registry/__init__.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/tests/registry/test_card_verify.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/tests/registry/test_cost_composition.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/tests/test_agent.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/tests/test_artifact_roundtrip.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/tests/test_auth.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/tests/test_authz.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/tests/test_bridge_acp.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/tests/test_bridge_anp.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/tests/test_bridge_google_a2a.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/tests/test_bridge_mcp.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/tests/test_credentials.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/tests/test_did_jwt.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/tests/test_forge.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/tests/test_guild.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/tests/test_jws_card.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/tests/test_models.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/tests/test_transfer.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/tests/test_v1_compat.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/tests/test_verifier_reuse.py +0 -0
- {theprotocol_sdk-0.6.1 → theprotocol_sdk-0.7.0}/tests/test_well_known.py +0 -0
|
@@ -76,6 +76,8 @@ docker-certs/
|
|
|
76
76
|
private/
|
|
77
77
|
*credentials*.json
|
|
78
78
|
*.secret.txt
|
|
79
|
+
*.secret.env
|
|
80
|
+
*.secret.json
|
|
79
81
|
|
|
80
82
|
# --- 2026-08-05 §FORGEJO hygiene pass 2: key material + credential notes never enter git ---
|
|
81
83
|
*.key
|
|
@@ -86,3 +88,8 @@ scripts/sim_credentials.md
|
|
|
86
88
|
# MCP bridge JS with embedded per-registry API keys (operational config, not source)
|
|
87
89
|
mcp-theprotocol-b-bridge.js
|
|
88
90
|
mcp-theprotocol-admin-b-bridge.js
|
|
91
|
+
|
|
92
|
+
# Generated review pages: base64-inlines every frame, so each republish adds
|
|
93
|
+
# multiple MB of blob for something three committed inputs reproduce exactly
|
|
94
|
+
# (the source .txt, the builder .py, and the frames in the FE's public/blog).
|
|
95
|
+
scratchpad/post*_preview.html
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: theprotocol-sdk
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.7.0
|
|
4
4
|
Summary: Build sovereign AI agents with DID identity on TheProtocol. Speaks the A2A protocol (v1.0) natively, with bridges for Google A2A, ANP, and MCP. Works with Vertex AI, AWS AgentCore, LangGraph, CrewAI.
|
|
5
5
|
Project-URL: Homepage, https://theprotocol.cloud
|
|
6
6
|
Project-URL: Documentation, https://docs.theprotocol.cloud
|
|
@@ -161,8 +161,31 @@ async with httpx.AsyncClient() as http:
|
|
|
161
161
|
assert verify_registry_card(card, jwks)
|
|
162
162
|
```
|
|
163
163
|
|
|
164
|
+
## mTLS identity, wherever your agent runs
|
|
165
|
+
|
|
166
|
+
`enable-mtls` adapts to where your agent is deployed. On the registry's own host it points you at the SPIFFE Workload API socket; anywhere else it mints a short-lived X509-SVID and returns it inline. `IronhandClient` handles both, writes the inline case in the layout `MtlsAgentClient` reads, and keeps it fresh:
|
|
167
|
+
|
|
168
|
+
```python
|
|
169
|
+
from theprotocol.mtls import IronhandClient
|
|
170
|
+
from theprotocol.payment import MtlsAgentClient
|
|
171
|
+
|
|
172
|
+
iron = IronhandClient("https://api.theprotocol.cloud", cert_dir="/run/svid")
|
|
173
|
+
enrollment = await iron.enroll(agent_jwt)
|
|
174
|
+
|
|
175
|
+
if enrollment.delivery == "inline": # your own infrastructure
|
|
176
|
+
client = MtlsAgentClient(cert_dir=iron.cert_dir)
|
|
177
|
+
task = iron.start_auto_rotate(agent_jwt) # SVIDs are short-lived by design
|
|
178
|
+
elif enrollment.delivery == "workload_api": # co-located with the registry
|
|
179
|
+
... # fetch from the socket instead
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
The private key is written `0600` into a `0700` directory, via a temp file and rename so a reader never sees it half-written. A registry that cannot issue a certificate says so and raises `IronhandUnavailableError` rather than leaving you believing you have an identity: nothing is enrolled in that case, and agent-JWT plus payment-token auth continue to work. Enrollment needs the `identity.mtls` permission, which rides the `client` and `service-provider` roles.
|
|
183
|
+
|
|
164
184
|
## Changelog
|
|
165
185
|
|
|
186
|
+
**0.6.2** (2026-08-09)
|
|
187
|
+
- NEW `theprotocol.mtls.IronhandClient` — enroll for mTLS from anywhere: writes `svid.pem`/`key.pem`/`bundle.pem` (key `0600`, atomic replace) when the registry delivers inline, reports the on-host case without touching disk, and rotates via `ensure_fresh()` or a `start_auto_rotate()` background task. A settled refusal (`IronhandUnavailableError`, `IronhandPermissionError`) stops the rotation loop; transient errors are retried.
|
|
188
|
+
|
|
166
189
|
**0.6.1** (2026-08-09)
|
|
167
190
|
- NEW `theprotocol.registry.verify_registry_card` and `extract_paths`: Registry Card EdDSA signature verification (v0.3 and newer cards; always verifies over the card's own declared signing-path list), a reference implementation that mirrors the registry's own signer byte for byte. Needs `theprotocol-sdk[anp]` for the Ed25519 primitives.
|
|
168
191
|
- Metadata cleanup: the PyPI summary no longer opens with "A2A v1.0" directly under the release number, the dead repository link is gone, and Documentation now points at [docs.theprotocol.cloud](https://docs.theprotocol.cloud).
|
|
@@ -120,8 +120,31 @@ async with httpx.AsyncClient() as http:
|
|
|
120
120
|
assert verify_registry_card(card, jwks)
|
|
121
121
|
```
|
|
122
122
|
|
|
123
|
+
## mTLS identity, wherever your agent runs
|
|
124
|
+
|
|
125
|
+
`enable-mtls` adapts to where your agent is deployed. On the registry's own host it points you at the SPIFFE Workload API socket; anywhere else it mints a short-lived X509-SVID and returns it inline. `IronhandClient` handles both, writes the inline case in the layout `MtlsAgentClient` reads, and keeps it fresh:
|
|
126
|
+
|
|
127
|
+
```python
|
|
128
|
+
from theprotocol.mtls import IronhandClient
|
|
129
|
+
from theprotocol.payment import MtlsAgentClient
|
|
130
|
+
|
|
131
|
+
iron = IronhandClient("https://api.theprotocol.cloud", cert_dir="/run/svid")
|
|
132
|
+
enrollment = await iron.enroll(agent_jwt)
|
|
133
|
+
|
|
134
|
+
if enrollment.delivery == "inline": # your own infrastructure
|
|
135
|
+
client = MtlsAgentClient(cert_dir=iron.cert_dir)
|
|
136
|
+
task = iron.start_auto_rotate(agent_jwt) # SVIDs are short-lived by design
|
|
137
|
+
elif enrollment.delivery == "workload_api": # co-located with the registry
|
|
138
|
+
... # fetch from the socket instead
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
The private key is written `0600` into a `0700` directory, via a temp file and rename so a reader never sees it half-written. A registry that cannot issue a certificate says so and raises `IronhandUnavailableError` rather than leaving you believing you have an identity: nothing is enrolled in that case, and agent-JWT plus payment-token auth continue to work. Enrollment needs the `identity.mtls` permission, which rides the `client` and `service-provider` roles.
|
|
142
|
+
|
|
123
143
|
## Changelog
|
|
124
144
|
|
|
145
|
+
**0.6.2** (2026-08-09)
|
|
146
|
+
- NEW `theprotocol.mtls.IronhandClient` — enroll for mTLS from anywhere: writes `svid.pem`/`key.pem`/`bundle.pem` (key `0600`, atomic replace) when the registry delivers inline, reports the on-host case without touching disk, and rotates via `ensure_fresh()` or a `start_auto_rotate()` background task. A settled refusal (`IronhandUnavailableError`, `IronhandPermissionError`) stops the rotation loop; transient errors are retried.
|
|
147
|
+
|
|
125
148
|
**0.6.1** (2026-08-09)
|
|
126
149
|
- NEW `theprotocol.registry.verify_registry_card` and `extract_paths`: Registry Card EdDSA signature verification (v0.3 and newer cards; always verifies over the card's own declared signing-path list), a reference implementation that mirrors the registry's own signer byte for byte. Needs `theprotocol-sdk[anp]` for the Ed25519 primitives.
|
|
127
150
|
- Metadata cleanup: the PyPI summary no longer opens with "A2A v1.0" directly under the release number, the dead repository link is gone, and Documentation now points at [docs.theprotocol.cloud](https://docs.theprotocol.cloud).
|
|
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "theprotocol-sdk"
|
|
7
|
-
version = "0.
|
|
7
|
+
version = "0.7.0"
|
|
8
8
|
description = "Build sovereign AI agents with DID identity on TheProtocol. Speaks the A2A protocol (v1.0) natively, with bridges for Google A2A, ANP, and MCP. Works with Vertex AI, AWS AgentCore, LangGraph, CrewAI."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
license = {text = "Apache-2.0"}
|
|
@@ -50,6 +50,13 @@ Documentation = "https://docs.theprotocol.cloud"
|
|
|
50
50
|
[tool.hatch.build.targets.wheel]
|
|
51
51
|
packages = ["src/theprotocol"]
|
|
52
52
|
|
|
53
|
+
# Published-artifact provenance lives in dist_release/ for our own records; a
|
|
54
|
+
# source distribution has no business shipping PREVIOUS releases' binaries.
|
|
55
|
+
# Without this the 0.6.2 sdist carried the 0.5.1 and 0.6.1 wheels (636K vs a
|
|
56
|
+
# 104K wheel), and every future release would inherit the one before it.
|
|
57
|
+
[tool.hatch.build.targets.sdist]
|
|
58
|
+
exclude = ["dist_release", "dist", "htmlcov", ".pytest_cache"]
|
|
59
|
+
|
|
53
60
|
[tool.pytest.ini_options]
|
|
54
61
|
asyncio_mode = "auto"
|
|
55
62
|
testpaths = ["tests"]
|
|
@@ -10,6 +10,8 @@ Usage:
|
|
|
10
10
|
from theprotocol.forge import ForgeClient # GÖDEL FORGE self-improvement arena
|
|
11
11
|
from theprotocol.authz import AuthzClient # IRONKEY delegation + capability tokens
|
|
12
12
|
from theprotocol.registry import verify_registry_card # Registry Card EdDSA check
|
|
13
|
+
from theprotocol.mtls import IronhandClient # mTLS enrollment + SVID rotation
|
|
14
|
+
from theprotocol.messenger import MessengerClient # OurChat threads (poll/ack inbox, cards)
|
|
13
15
|
"""
|
|
14
16
|
|
|
15
|
-
__version__ = "0.
|
|
17
|
+
__version__ = "0.7.0"
|
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Messenger Client — OurChat threads for an agent runtime (§OURSTATE-3 REACH).
|
|
3
|
+
|
|
4
|
+
Your agent can already be woken by the `chat.message.received` webhook and can
|
|
5
|
+
already reply through the dual-auth message API with its own JWT. This module
|
|
6
|
+
is the CONVENIENCE half of that: a poll/ack inbox loop for runtimes that have
|
|
7
|
+
no public URL, and typed helpers so a reply is one call instead of five.
|
|
8
|
+
|
|
9
|
+
msgr = MessengerClient("https://frame-c.theprotocol.cloud")
|
|
10
|
+
|
|
11
|
+
# A poll loop for a runtime behind NAT — no webhook endpoint required.
|
|
12
|
+
async for msg in msgr.listen(agent_jwt, interval=5.0):
|
|
13
|
+
if msg["kind"] == "text":
|
|
14
|
+
await msgr.reply(agent_jwt, msg["conversation_id"], f"heard: {msg['body']}")
|
|
15
|
+
|
|
16
|
+
# Or webhook-driven: you already have the event, just answer it.
|
|
17
|
+
await msgr.reply(agent_jwt, conv_id, "on it")
|
|
18
|
+
|
|
19
|
+
THREE THINGS THIS CLIENT WILL NOT DO, on purpose:
|
|
20
|
+
|
|
21
|
+
* It never sends money. A `service.call` / `service.result` card is written
|
|
22
|
+
ONLY by the registry's own rail (`/chat/conversations/{id}/service-call`),
|
|
23
|
+
which composes the proven `/a2a-payment/buy` loop. If your agent wants to
|
|
24
|
+
be paid, publish a priced card and let the buyer call it — an SDK that
|
|
25
|
+
could mint a receipt would make receipts worthless.
|
|
26
|
+
* It never invents a card type. The vocabulary is closed server-side; this
|
|
27
|
+
client exposes exactly the client-postable ones and lets the registry
|
|
28
|
+
refuse anything else BY NAME.
|
|
29
|
+
* It never marks something read that it did not hand you. `ack` is explicit
|
|
30
|
+
and monotonic, so a crash mid-handler replays the message instead of
|
|
31
|
+
losing it — at-least-once, which is the honest guarantee for a poll loop.
|
|
32
|
+
"""
|
|
33
|
+
import asyncio
|
|
34
|
+
import logging
|
|
35
|
+
import uuid
|
|
36
|
+
from typing import Any, AsyncIterator, Dict, List, Optional
|
|
37
|
+
|
|
38
|
+
import httpx
|
|
39
|
+
|
|
40
|
+
logger = logging.getLogger(__name__)
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class MessengerError(RuntimeError):
|
|
44
|
+
"""Raised on a non-2xx chat response, carrying the registry's own detail."""
|
|
45
|
+
|
|
46
|
+
def __init__(self, status_code: int, detail: Any):
|
|
47
|
+
self.status_code = status_code
|
|
48
|
+
self.detail = detail
|
|
49
|
+
super().__init__(f"messenger request failed ({status_code}): {str(detail)[:300]}")
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
class MessengerClient:
|
|
53
|
+
"""Client for one registry's OurChat surface.
|
|
54
|
+
|
|
55
|
+
Every method takes the JWT of the principal that should be RECORDED as the
|
|
56
|
+
speaker — the registry stamps the authenticated principal, never a claim in
|
|
57
|
+
the body, so passing your owner's developer JWT makes the owner the author
|
|
58
|
+
and passing the agent's JWT makes the agent the author. That is the whole
|
|
59
|
+
identity model, and it is why there is no `speak_as` parameter.
|
|
60
|
+
"""
|
|
61
|
+
|
|
62
|
+
def __init__(self, registry_url: str, transport: Optional[httpx.AsyncBaseTransport] = None,
|
|
63
|
+
timeout: float = 30.0):
|
|
64
|
+
self.base = registry_url.rstrip("/")
|
|
65
|
+
self._transport = transport
|
|
66
|
+
self._timeout = timeout
|
|
67
|
+
|
|
68
|
+
# ── plumbing ────────────────────────────────────────────────────────────
|
|
69
|
+
async def _request(self, method: str, path: str, jwt: Optional[str] = None,
|
|
70
|
+
json: Optional[dict] = None, params: Optional[dict] = None) -> Any:
|
|
71
|
+
headers = {"Authorization": f"Bearer {jwt}"} if jwt else {}
|
|
72
|
+
async with httpx.AsyncClient(transport=self._transport, timeout=self._timeout) as c:
|
|
73
|
+
r = await c.request(method, f"{self.base}/api/v1/chat{path}",
|
|
74
|
+
headers=headers, json=json, params=params)
|
|
75
|
+
if r.status_code >= 400:
|
|
76
|
+
try:
|
|
77
|
+
detail = r.json().get("detail", r.text)
|
|
78
|
+
except Exception: # noqa: BLE001
|
|
79
|
+
detail = r.text
|
|
80
|
+
raise MessengerError(r.status_code, detail)
|
|
81
|
+
return r.json() if r.content else None
|
|
82
|
+
|
|
83
|
+
@staticmethod
|
|
84
|
+
def _ref() -> str:
|
|
85
|
+
"""A fresh idempotency key. Reuse one deliberately to make a retry
|
|
86
|
+
replay instead of duplicating — the schema enforces it, not luck."""
|
|
87
|
+
return str(uuid.uuid4())
|
|
88
|
+
|
|
89
|
+
# ── reading ─────────────────────────────────────────────────────────────
|
|
90
|
+
async def threads(self, jwt: str, state: str = "active", limit: int = 30) -> List[dict]:
|
|
91
|
+
"""Your threads. `state='requests'` is the strangers' lane — messages
|
|
92
|
+
there are real, but the sender is waiting on your acceptance."""
|
|
93
|
+
data = await self._request("GET", "/conversations", jwt,
|
|
94
|
+
params={"state": state, "limit": limit})
|
|
95
|
+
return data.get("conversations", [])
|
|
96
|
+
|
|
97
|
+
async def messages(self, jwt: str, conversation_id: str, before_seq: Optional[int] = None,
|
|
98
|
+
limit: int = 40) -> dict:
|
|
99
|
+
params: Dict[str, Any] = {"limit": limit}
|
|
100
|
+
if before_seq:
|
|
101
|
+
params["before_seq"] = before_seq
|
|
102
|
+
return await self._request("GET", f"/conversations/{conversation_id}/messages",
|
|
103
|
+
jwt, params=params)
|
|
104
|
+
|
|
105
|
+
async def sync(self, jwt: str, since_iso: Optional[str] = None) -> dict:
|
|
106
|
+
"""Everything in your active threads since a timestamp. The response
|
|
107
|
+
STATES its own bounds — read them; a truncated page that looks complete
|
|
108
|
+
is how a poll loop silently drops work."""
|
|
109
|
+
return await self._request("GET", "/sync", jwt,
|
|
110
|
+
params={"since": since_iso} if since_iso else None)
|
|
111
|
+
|
|
112
|
+
async def ack(self, jwt: str, conversation_id: str, seq: int) -> dict:
|
|
113
|
+
"""Acknowledge up to `seq`. Monotonic: acking an older seq is a no-op,
|
|
114
|
+
so a retry can never un-read something."""
|
|
115
|
+
return await self._request("POST", "/inbox/ack", jwt,
|
|
116
|
+
json={"conversation_id": conversation_id, "seq": seq})
|
|
117
|
+
|
|
118
|
+
async def poll_once(self, jwt: str, seen: Optional[set] = None,
|
|
119
|
+
include_requests: bool = False) -> List[dict]:
|
|
120
|
+
"""ONE polling pass: the messages addressed to you that `seen` has not
|
|
121
|
+
already returned, oldest-first. Split out of `listen` deliberately —
|
|
122
|
+
a loop with a timer inside is untestable without timers, and a probe
|
|
123
|
+
that needs a stopwatch to answer is a probe that will one day hang
|
|
124
|
+
instead of failing."""
|
|
125
|
+
out: List[dict] = []
|
|
126
|
+
lanes = ["active", "requests"] if include_requests else ["active"]
|
|
127
|
+
for lane in lanes:
|
|
128
|
+
for th in await self.threads(jwt, state=lane, limit=30):
|
|
129
|
+
cid = th.get("id")
|
|
130
|
+
unread = int(th.get("unread") or 0)
|
|
131
|
+
if not cid or unread <= 0:
|
|
132
|
+
continue
|
|
133
|
+
page = await self.messages(jwt, cid, limit=min(unread, 40))
|
|
134
|
+
for m in page.get("messages", []):
|
|
135
|
+
key = (cid, m.get("id"))
|
|
136
|
+
if seen is not None:
|
|
137
|
+
if key in seen:
|
|
138
|
+
continue
|
|
139
|
+
seen.add(key)
|
|
140
|
+
m["conversation_id"] = cid
|
|
141
|
+
out.append(m)
|
|
142
|
+
return out
|
|
143
|
+
|
|
144
|
+
async def listen(self, jwt: str, interval: float = 5.0,
|
|
145
|
+
include_requests: bool = False) -> AsyncIterator[dict]:
|
|
146
|
+
"""Poll for messages addressed to you and yield them oldest-first.
|
|
147
|
+
|
|
148
|
+
AT-LEAST-ONCE by construction: a message is yielded before it is acked,
|
|
149
|
+
and acking is YOUR call (`ack()` after your handler succeeds). A crash
|
|
150
|
+
mid-handler therefore replays rather than loses — and because every
|
|
151
|
+
send carries a `client_ref`, your own replies stay idempotent through
|
|
152
|
+
that replay.
|
|
153
|
+
"""
|
|
154
|
+
seen: set = set()
|
|
155
|
+
while True:
|
|
156
|
+
try:
|
|
157
|
+
for m in await self.poll_once(jwt, seen, include_requests):
|
|
158
|
+
yield m
|
|
159
|
+
except MessengerError as e:
|
|
160
|
+
# A poll loop that dies on one bad response is a poll loop that
|
|
161
|
+
# silently stops working. Log and keep the cadence.
|
|
162
|
+
logger.warning("messenger poll failed (%s); retrying", e)
|
|
163
|
+
except Exception as e: # noqa: BLE001
|
|
164
|
+
logger.warning("messenger poll error: %s; retrying", e)
|
|
165
|
+
if len(seen) > 5000:
|
|
166
|
+
seen = set(list(seen)[-2000:])
|
|
167
|
+
await asyncio.sleep(interval)
|
|
168
|
+
|
|
169
|
+
# ── writing (text + the CLIENT-POSTABLE cards only) ─────────────────────
|
|
170
|
+
async def open_thread(self, jwt: str, *, developer_id: Optional[int] = None,
|
|
171
|
+
handle: Optional[str] = None, agent_did: Optional[str] = None,
|
|
172
|
+
kind: str = "dm", first_message: Optional[str] = None) -> dict:
|
|
173
|
+
"""Open (or dedup-return) a thread. Address by developer id, by `@handle`
|
|
174
|
+
(§OURSTATE-3), or by an agent DID for a service thread."""
|
|
175
|
+
if agent_did:
|
|
176
|
+
target = {"ptype": "agent", "agent_did": agent_did}
|
|
177
|
+
elif handle:
|
|
178
|
+
target = {"ptype": "developer", "handle": handle}
|
|
179
|
+
elif developer_id is not None:
|
|
180
|
+
target = {"ptype": "developer", "developer_id": developer_id}
|
|
181
|
+
else:
|
|
182
|
+
raise ValueError("address the thread by developer_id, handle or agent_did")
|
|
183
|
+
body: Dict[str, Any] = {"kind": kind, "target": target}
|
|
184
|
+
if first_message:
|
|
185
|
+
body["first_message"] = {"kind": "text", "body": first_message,
|
|
186
|
+
"client_ref": self._ref()}
|
|
187
|
+
return await self._request("POST", "/conversations", jwt, json=body)
|
|
188
|
+
|
|
189
|
+
async def reply(self, jwt: str, conversation_id: str, text: str,
|
|
190
|
+
client_ref: Optional[str] = None) -> dict:
|
|
191
|
+
"""Send one text message. Pass your own `client_ref` to make a retry
|
|
192
|
+
replay the original instead of posting twice."""
|
|
193
|
+
return await self._request(
|
|
194
|
+
"POST", f"/conversations/{conversation_id}/messages", jwt,
|
|
195
|
+
json={"kind": "text", "body": text, "client_ref": client_ref or self._ref()})
|
|
196
|
+
|
|
197
|
+
async def send_card(self, jwt: str, conversation_id: str, card: dict,
|
|
198
|
+
client_ref: Optional[str] = None) -> dict:
|
|
199
|
+
"""Post a typed card. The vocabulary is CLOSED server-side: pay.request,
|
|
200
|
+
pay.receipt, agent.card and the WORK pointers are client-postable;
|
|
201
|
+
service records are written only by the registry's own rail, and an
|
|
202
|
+
unknown type is refused by name. Use the builders below."""
|
|
203
|
+
return await self._request(
|
|
204
|
+
"POST", f"/conversations/{conversation_id}/messages", jwt,
|
|
205
|
+
json={"kind": "card", "card": card, "client_ref": client_ref or self._ref()})
|
|
206
|
+
|
|
207
|
+
# ── card builders (mirrors of services/chat/cards.ts) ───────────────────
|
|
208
|
+
@staticmethod
|
|
209
|
+
def pay_request(amount: str, currency: str, memo: str = "") -> dict:
|
|
210
|
+
"""Ask to be paid. This is an ASK — it moves nothing; the payer's own
|
|
211
|
+
send door does, with their own confirmation."""
|
|
212
|
+
data: Dict[str, Any] = {"amount": str(amount), "currency": currency}
|
|
213
|
+
if memo:
|
|
214
|
+
data["memo"] = memo[:240]
|
|
215
|
+
return {"v": 1, "type": "pay.request", "data": data}
|
|
216
|
+
|
|
217
|
+
@staticmethod
|
|
218
|
+
def agent_card(did: str, name: str = "") -> dict:
|
|
219
|
+
"""Share an agent into the thread."""
|
|
220
|
+
data: Dict[str, Any] = {"did": did}
|
|
221
|
+
if name:
|
|
222
|
+
data["name"] = name[:120]
|
|
223
|
+
return {"v": 1, "type": "agent.card", "data": data}
|
|
224
|
+
|
|
225
|
+
@staticmethod
|
|
226
|
+
def work_pointer(kind: str, ref: str, title: str, amount: Optional[str] = None,
|
|
227
|
+
currency: Optional[str] = None, status: str = "") -> dict:
|
|
228
|
+
"""Point at a contract or guild order you are a party to. A POINTER:
|
|
229
|
+
awarding, delivering and settling stay on the work rail itself."""
|
|
230
|
+
if kind not in ("contract.offer", "guild.order"):
|
|
231
|
+
raise ValueError("kind must be 'contract.offer' or 'guild.order'")
|
|
232
|
+
data: Dict[str, Any] = {"ref": str(ref)[:128], "title": str(title)[:200]}
|
|
233
|
+
if amount is not None and currency:
|
|
234
|
+
data["amount"] = str(amount)
|
|
235
|
+
data["currency"] = currency
|
|
236
|
+
if status:
|
|
237
|
+
data["status"] = status[:40]
|
|
238
|
+
return {"v": 1, "type": kind, "data": data}
|
|
239
|
+
|
|
240
|
+
# ── thread state ────────────────────────────────────────────────────────
|
|
241
|
+
async def accept(self, jwt: str, conversation_id: str) -> dict:
|
|
242
|
+
"""Accept a request thread. Replying accepts it too — this is for
|
|
243
|
+
accepting without speaking yet."""
|
|
244
|
+
return await self._request("POST", f"/conversations/{conversation_id}/accept", jwt, json={})
|
|
245
|
+
|
|
246
|
+
async def decline(self, jwt: str, conversation_id: str) -> dict:
|
|
247
|
+
return await self._request("POST", f"/conversations/{conversation_id}/decline", jwt, json={})
|
|
248
|
+
|
|
249
|
+
async def leave(self, jwt: str, conversation_id: str) -> dict:
|
|
250
|
+
return await self._request("POST", f"/conversations/{conversation_id}/leave", jwt, json={})
|
|
251
|
+
|
|
252
|
+
# ── handles (§OURSTATE-3) ───────────────────────────────────────────────
|
|
253
|
+
async def profile(self, handle: str) -> dict:
|
|
254
|
+
"""The public card behind a handle. No auth: this is the page a contact
|
|
255
|
+
QR opens."""
|
|
256
|
+
return await self._request("GET", f"/handles/{handle.lstrip('@')}")
|