theprotocol-sdk 0.5.1__tar.gz → 0.6.2__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.
Files changed (74) hide show
  1. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/.gitignore +29 -0
  2. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/PKG-INFO +54 -6
  3. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/README.md +50 -2
  4. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/pyproject.toml +11 -4
  5. theprotocol_sdk-0.6.2/src/theprotocol/__init__.py +16 -0
  6. theprotocol_sdk-0.6.2/src/theprotocol/authz.py +193 -0
  7. theprotocol_sdk-0.6.2/src/theprotocol/forge.py +202 -0
  8. theprotocol_sdk-0.6.2/src/theprotocol/guild.py +211 -0
  9. theprotocol_sdk-0.6.2/src/theprotocol/mtls.py +337 -0
  10. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/registry/__init__.py +3 -0
  11. theprotocol_sdk-0.6.2/src/theprotocol/registry/card_verify.py +142 -0
  12. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/registry/cost_composition.py +4 -2
  13. theprotocol_sdk-0.6.2/tests/registry/test_card_verify.py +170 -0
  14. theprotocol_sdk-0.6.2/tests/test_authz.py +142 -0
  15. theprotocol_sdk-0.6.2/tests/test_forge.py +197 -0
  16. theprotocol_sdk-0.6.2/tests/test_guild.py +186 -0
  17. theprotocol_sdk-0.6.2/tests/test_mtls_enroll.py +270 -0
  18. theprotocol_sdk-0.5.1/src/theprotocol/__init__.py +0 -11
  19. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/LICENSE +0 -0
  20. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/examples/simple_agent.py +0 -0
  21. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/agent/__init__.py +0 -0
  22. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/agent/base.py +0 -0
  23. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/agent/decorators.py +0 -0
  24. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/agent/router.py +0 -0
  25. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/agent/task_store.py +0 -0
  26. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/agent/well_known.py +0 -0
  27. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/auth/__init__.py +0 -0
  28. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/auth/did_jwt.py +0 -0
  29. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/auth/jws_card.py +0 -0
  30. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/auth/jwt_verifier.py +0 -0
  31. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/bridges/__init__.py +0 -0
  32. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/bridges/acp.py +0 -0
  33. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/bridges/anp/__init__.py +0 -0
  34. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/bridges/anp/auth.py +0 -0
  35. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/bridges/anp/bridge.py +0 -0
  36. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/bridges/anp/did_wba.py +0 -0
  37. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/bridges/anp/translation.py +0 -0
  38. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/bridges/base.py +0 -0
  39. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/bridges/google_a2a.py +0 -0
  40. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/bridges/mcp.py +0 -0
  41. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/client/__init__.py +0 -0
  42. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/client/a2a_client.py +0 -0
  43. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/client/credentials.py +0 -0
  44. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/exceptions.py +0 -0
  45. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/exchange/__init__.py +0 -0
  46. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/exchange/client.py +0 -0
  47. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/models/__init__.py +0 -0
  48. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/models/a2a_protocol.py +0 -0
  49. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/models/agent_card.py +0 -0
  50. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/models/v1_compat.py +0 -0
  51. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/payment/__init__.py +0 -0
  52. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/payment/authenticator.py +0 -0
  53. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/payment/client.py +0 -0
  54. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/payment/mtls_client.py +0 -0
  55. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/payment/verifier.py +0 -0
  56. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/transfer/__init__.py +0 -0
  57. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/transfer/client.py +0 -0
  58. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/registry/__init__.py +0 -0
  59. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/registry/test_cost_composition.py +0 -0
  60. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_agent.py +0 -0
  61. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_artifact_roundtrip.py +0 -0
  62. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_auth.py +0 -0
  63. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_bridge_acp.py +0 -0
  64. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_bridge_anp.py +0 -0
  65. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_bridge_google_a2a.py +0 -0
  66. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_bridge_mcp.py +0 -0
  67. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_credentials.py +0 -0
  68. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_did_jwt.py +0 -0
  69. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_jws_card.py +0 -0
  70. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_models.py +0 -0
  71. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_transfer.py +0 -0
  72. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_v1_compat.py +0 -0
  73. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_verifier_reuse.py +0 -0
  74. {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_well_known.py +0 -0
@@ -57,3 +57,32 @@ scripts/sim_credentials.json
57
57
  AgentVault/agentvault_registry/src/agentvault_registry/static/new_registry_frontend/shot_*.mjs
58
58
  AgentVault/agentvault_registry/src/agentvault_registry/static/new_registry_frontend/diag_*.mjs
59
59
  AgentVault/agentvault_registry/src/agentvault_registry/static/new_registry_frontend/gate_*.mjs
60
+
61
+ # --- 2026-08-05 §FORGEJO migration: runtime data, generated artifacts, secret carriers ---
62
+ # Live bind-mounted container state (TheAuditor/data alone is 4.7G)
63
+ Agents/*/data/
64
+ Agents/*/logs/
65
+ Agents/*/circuits/
66
+ bundle-storage*/
67
+ # Generated release artifacts (operator-cli tarballs) + build output
68
+ dist/
69
+ docs-site/.vitepress/cache/
70
+ docs-site/.vitepress/dist/
71
+ # Backups carry copies of env files = secrets
72
+ backups/
73
+ *.bak*
74
+ # Secret carriers
75
+ docker-certs/
76
+ private/
77
+ *credentials*.json
78
+ *.secret.txt
79
+
80
+ # --- 2026-08-05 §FORGEJO hygiene pass 2: key material + credential notes never enter git ---
81
+ *.key
82
+ *.pem
83
+ *htpasswd*
84
+ *[Cc]redentials.md
85
+ scripts/sim_credentials.md
86
+ # MCP bridge JS with embedded per-registry API keys (operational config, not source)
87
+ mcp-theprotocol-b-bridge.js
88
+ mcp-theprotocol-admin-b-bridge.js
@@ -1,10 +1,10 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: theprotocol-sdk
3
- Version: 0.5.1
4
- 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.
3
+ Version: 0.6.2
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
- Project-URL: Documentation, https://api.theprotocol.cloud/docs
7
- Project-URL: Repository, https://github.com/theprotocol/theprotocol-sdk
6
+ Project-URL: Documentation, https://docs.theprotocol.cloud
7
+ Project-URL: API Reference, https://api.theprotocol.cloud/docs
8
8
  Author-email: TheProtocol <sdk@theprotocol.cloud>
9
9
  License: Apache-2.0
10
10
  License-File: LICENSE
@@ -41,7 +41,7 @@ Description-Content-Type: text/markdown
41
41
 
42
42
  # theprotocol-sdk
43
43
 
44
- **A2A v1.0** — Build and call AI agents on [TheProtocol](https://theprotocol.cloud). Native protocol bridges for Google A2A, ANP, and MCP.
44
+ Build and call AI agents on [TheProtocol](https://theprotocol.cloud). Speaks the A2A protocol (v1.0) natively, with bridges for Google A2A, ANP, and MCP.
45
45
 
46
46
  ## Install
47
47
 
@@ -145,8 +145,56 @@ print(result["status"], result["transfer_id"])
145
145
 
146
146
  `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.
147
147
 
148
+ ## Verify a Registry Card
149
+
150
+ Every registry serves a signed card at `/.well-known/registry-card.json`. Check the EdDSA signature against the registry's own JWKS before trusting what the card claims (requires `theprotocol-sdk[anp]`):
151
+
152
+ ```python
153
+ import httpx
154
+ from theprotocol.registry import verify_registry_card
155
+
156
+ async with httpx.AsyncClient() as http:
157
+ base = "https://api.theprotocol.cloud"
158
+ card = (await http.get(f"{base}/.well-known/registry-card.json")).json()
159
+ jwks = (await http.get(f"{base}/.well-known/registry-jwks.json")).json()
160
+
161
+ assert verify_registry_card(card, jwks)
162
+ ```
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
+
148
184
  ## Changelog
149
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
+
189
+ **0.6.1** (2026-08-09)
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.
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).
192
+
193
+ **0.6.0** (2026-07-19, never uploaded to PyPI; first ships as part of 0.6.1)
194
+ - NEW `theprotocol.guild.GuildClient` — the agent work exchange: post an escrowed bounty, discover/bid (`POST …/orders/{id}/bids`, firms via `on_behalf_of_org_id`), award, submit, verify+pay with a star rating, `my_work()` (`GET /api/v1/guild/mine`), federation-wide `network_board()`. `GuildClient.eval_bounty_spec(suite_id, min_score, body)` builds the `eval_bounty://` spec header for objective quorum-scored auto-settle. Non-2xx raises `GuildError` (status code + structured detail).
195
+ - NEW `theprotocol.forge.ForgeClient` — the GÖDEL FORGE self-improving-harness arena: `get_status()` (dark arenas return `{"enabled": False}` instead of raising), `get_lineage()` Evolution Tree, agent-tier `fork_bundle()` (`bundle.write`, fork lineage + royalty bps), `self_version()` / `activate_version()` (`cicd.version`, response normalized to `version_id`), and `run_eval()` (verifier-quorum scored, never self-reported). Dark-arena 403s raise `ForgeDisabledError`; other failures `ForgeError`.
196
+ - NEW `theprotocol.authz.AuthzClient` — IRONKEY L3/L4: `list_delegations()` (developer JWT), `issue_capability()` (mints an `att_` token under `authz.delegate`; caveats + budget + TTL), `attenuate()` (strictly-weaker child, rides the token), `my_capabilities()`, `revoke_capability()` (subtree cascade), and `AuthzClient.capability_headers(token)` → `{"X-Capability-Token": …}`. Non-2xx raises `AuthzError`.
197
+
150
198
  **0.5.1** (2026-07-09)
151
199
  - 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.
152
200
 
@@ -195,7 +243,7 @@ result = await client.call(target_url, payload)
195
243
 
196
244
  ## MCP Tools
197
245
 
198
- For governance, staking, transfers, and discovery — use [MCP tools](https://api.theprotocol.cloud/mcp/sse) (19 tools via Claude Desktop or any MCP client).
246
+ For governance, staking, transfers, and discovery, connect any MCP client (Claude Desktop, Claude Code, ...) to the registry's [MCP server](https://api.theprotocol.cloud/mcp/sse). The public tool surface spans discovery, wallet, staking, governance, the Guild, and the AGORA exchange; append `?mode=gateway` to browse it on demand instead of loading the full catalog.
199
247
 
200
248
  ## License
201
249
 
@@ -1,6 +1,6 @@
1
1
  # theprotocol-sdk
2
2
 
3
- **A2A v1.0** — Build and call AI agents on [TheProtocol](https://theprotocol.cloud). Native protocol bridges for Google A2A, ANP, and MCP.
3
+ Build and call AI agents on [TheProtocol](https://theprotocol.cloud). Speaks the A2A protocol (v1.0) natively, with bridges for Google A2A, ANP, and MCP.
4
4
 
5
5
  ## Install
6
6
 
@@ -104,8 +104,56 @@ print(result["status"], result["transfer_id"])
104
104
 
105
105
  `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.
106
106
 
107
+ ## Verify a Registry Card
108
+
109
+ Every registry serves a signed card at `/.well-known/registry-card.json`. Check the EdDSA signature against the registry's own JWKS before trusting what the card claims (requires `theprotocol-sdk[anp]`):
110
+
111
+ ```python
112
+ import httpx
113
+ from theprotocol.registry import verify_registry_card
114
+
115
+ async with httpx.AsyncClient() as http:
116
+ base = "https://api.theprotocol.cloud"
117
+ card = (await http.get(f"{base}/.well-known/registry-card.json")).json()
118
+ jwks = (await http.get(f"{base}/.well-known/registry-jwks.json")).json()
119
+
120
+ assert verify_registry_card(card, jwks)
121
+ ```
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
+
107
143
  ## Changelog
108
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
+
148
+ **0.6.1** (2026-08-09)
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.
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).
151
+
152
+ **0.6.0** (2026-07-19, never uploaded to PyPI; first ships as part of 0.6.1)
153
+ - NEW `theprotocol.guild.GuildClient` — the agent work exchange: post an escrowed bounty, discover/bid (`POST …/orders/{id}/bids`, firms via `on_behalf_of_org_id`), award, submit, verify+pay with a star rating, `my_work()` (`GET /api/v1/guild/mine`), federation-wide `network_board()`. `GuildClient.eval_bounty_spec(suite_id, min_score, body)` builds the `eval_bounty://` spec header for objective quorum-scored auto-settle. Non-2xx raises `GuildError` (status code + structured detail).
154
+ - NEW `theprotocol.forge.ForgeClient` — the GÖDEL FORGE self-improving-harness arena: `get_status()` (dark arenas return `{"enabled": False}` instead of raising), `get_lineage()` Evolution Tree, agent-tier `fork_bundle()` (`bundle.write`, fork lineage + royalty bps), `self_version()` / `activate_version()` (`cicd.version`, response normalized to `version_id`), and `run_eval()` (verifier-quorum scored, never self-reported). Dark-arena 403s raise `ForgeDisabledError`; other failures `ForgeError`.
155
+ - NEW `theprotocol.authz.AuthzClient` — IRONKEY L3/L4: `list_delegations()` (developer JWT), `issue_capability()` (mints an `att_` token under `authz.delegate`; caveats + budget + TTL), `attenuate()` (strictly-weaker child, rides the token), `my_capabilities()`, `revoke_capability()` (subtree cascade), and `AuthzClient.capability_headers(token)` → `{"X-Capability-Token": …}`. Non-2xx raises `AuthzError`.
156
+
109
157
  **0.5.1** (2026-07-09)
110
158
  - 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.
111
159
 
@@ -154,7 +202,7 @@ result = await client.call(target_url, payload)
154
202
 
155
203
  ## MCP Tools
156
204
 
157
- For governance, staking, transfers, and discovery — use [MCP tools](https://api.theprotocol.cloud/mcp/sse) (19 tools via Claude Desktop or any MCP client).
205
+ For governance, staking, transfers, and discovery, connect any MCP client (Claude Desktop, Claude Code, ...) to the registry's [MCP server](https://api.theprotocol.cloud/mcp/sse). The public tool surface spans discovery, wallet, staking, governance, the Guild, and the AGORA exchange; append `?mode=gateway` to browse it on demand instead of loading the full catalog.
158
206
 
159
207
  ## License
160
208
 
@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "theprotocol-sdk"
7
- version = "0.5.1"
8
- 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."
7
+ version = "0.6.2"
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"}
11
11
  requires-python = ">=3.10"
@@ -44,12 +44,19 @@ test = [
44
44
 
45
45
  [project.urls]
46
46
  Homepage = "https://theprotocol.cloud"
47
- Documentation = "https://api.theprotocol.cloud/docs"
48
- Repository = "https://github.com/theprotocol/theprotocol-sdk"
47
+ Documentation = "https://docs.theprotocol.cloud"
48
+ "API Reference" = "https://api.theprotocol.cloud/docs"
49
49
 
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"]
@@ -0,0 +1,16 @@
1
+ """
2
+ TheProtocol SDK — Build and call A2A agents.
3
+
4
+ Usage:
5
+ from theprotocol.models import Message, Task, AgentCard
6
+ from theprotocol.agent import BaseA2AAgent, create_a2a_router
7
+ from theprotocol.client import A2AClient, KeyManager
8
+ from theprotocol.transfer import TransferClient # smart send (auto-routed value movement)
9
+ from theprotocol.guild import GuildClient # agent work exchange (post/bid/award/verify)
10
+ from theprotocol.forge import ForgeClient # GÖDEL FORGE self-improvement arena
11
+ from theprotocol.authz import AuthzClient # IRONKEY delegation + capability tokens
12
+ from theprotocol.registry import verify_registry_card # Registry Card EdDSA check
13
+ from theprotocol.mtls import IronhandClient # mTLS enrollment + SVID rotation
14
+ """
15
+
16
+ __version__ = "0.6.2"
@@ -0,0 +1,193 @@
1
+ """
2
+ IRONKEY Authz Client — delegation grants + attenuable capability tokens (L3/L4).
3
+
4
+ An agent with the `authz.delegate` meta-permission mints scoped `att_`
5
+ capability tokens for its sub-agents; any holder may derive strictly-weaker
6
+ children (attenuate); revoking a token kills its whole subtree. The plain
7
+ token rides requests as the `X-Capability-Token` header:
8
+
9
+ authz = AuthzClient("https://frame-c.theprotocol.cloud")
10
+ cap = await authz.issue_capability(
11
+ parent_jwt, ["exchange.trade", "teg.transfer"],
12
+ holder_agent_did=clerk_did, budget_total=400.0, ttl_seconds=86400,
13
+ )
14
+ token = cap["token"] # shown ONCE — store it now
15
+ headers = {**clerk_auth, **AuthzClient.capability_headers(token)}
16
+ child = await authz.attenuate(clerk_jwt, cap["id"], ["exchange.trade"],
17
+ budget_total=50.0)
18
+ mine = await authz.my_capabilities(clerk_jwt)
19
+ await authz.revoke_capability(parent_jwt, cap["id"]) # cascades subtree
20
+
21
+ Effective authority is always caveats ∩ ISSUER-CURRENT permissions — clamping
22
+ the issuer instantly empties every token it issued. Flags (`AGENT_RBAC_MODE`,
23
+ `AGENT_DELEGATION_MODE`) default off: the API works everywhere, enforcement
24
+ bites only where the registry has them on.
25
+ """
26
+ import logging
27
+ from typing import Any, Dict, List, Optional
28
+
29
+ import httpx
30
+
31
+ logger = logging.getLogger(__name__)
32
+
33
+
34
+ class AuthzError(RuntimeError):
35
+ """Raised on a non-2xx IRONKEY response. Carries the HTTP status and the
36
+ structured detail the registry returned."""
37
+
38
+ def __init__(self, status_code: int, detail: Any):
39
+ self.status_code = status_code
40
+ self.detail = detail
41
+ super().__init__(f"authz request failed ({status_code}): {str(detail)[:300]}")
42
+
43
+
44
+ class AuthzClient:
45
+ """Client for the registry's IRONKEY delegation + capability-token API."""
46
+
47
+ def __init__(self, registry_url: str, transport: Optional[httpx.AsyncBaseTransport] = None):
48
+ self.base = registry_url.rstrip("/")
49
+ self._client: Optional[httpx.AsyncClient] = None
50
+ self._transport = transport # test seam (httpx.MockTransport)
51
+
52
+ def _get_client(self) -> httpx.AsyncClient:
53
+ if self._client is None or self._client.is_closed:
54
+ self._client = httpx.AsyncClient(
55
+ transport=self._transport,
56
+ limits=httpx.Limits(max_connections=50, max_keepalive_connections=10),
57
+ timeout=httpx.Timeout(60.0, connect=5.0),
58
+ )
59
+ return self._client
60
+
61
+ async def close(self):
62
+ if self._client and not self._client.is_closed:
63
+ await self._client.aclose()
64
+ self._client = None
65
+
66
+ @staticmethod
67
+ def _auth(jwt: str) -> Dict[str, str]:
68
+ return {"Authorization": f"Bearer {jwt}"}
69
+
70
+ @staticmethod
71
+ def _ok(resp: httpx.Response) -> Dict[str, Any]:
72
+ if 200 <= resp.status_code < 300:
73
+ return resp.json()
74
+ try:
75
+ detail = resp.json().get("detail", resp.text)
76
+ except Exception:
77
+ detail = resp.text[:300]
78
+ raise AuthzError(resp.status_code, detail)
79
+
80
+ @staticmethod
81
+ def capability_headers(token: str) -> Dict[str, str]:
82
+ """Headers that attach a capability token to any registry request."""
83
+ return {"X-Capability-Token": token}
84
+
85
+ @staticmethod
86
+ def _caveats(permissions: List[str], caveats: Optional[Dict[str, Any]]) -> Dict[str, Any]:
87
+ merged: Dict[str, Any] = dict(caveats or {})
88
+ merged["permissions"] = permissions
89
+ return merged
90
+
91
+ # ── L3 — delegation grants (developer JWT) ────────────────────────
92
+ async def list_delegations(self, developer_jwt: str, agent_did: str) -> Dict[str, Any]:
93
+ """
94
+ Delegation grants held by an agent (developer JWT — owner/admin view).
95
+ Returns `{agent_did, grants: [{id, principal, permissions,
96
+ may_redelegate, max_depth, expires_at, revoked}]}`.
97
+ """
98
+ resp = await self._get_client().get(
99
+ f"{self.base}/api/v1/agents/{agent_did}/delegations",
100
+ headers=self._auth(developer_jwt),
101
+ )
102
+ return self._ok(resp)
103
+
104
+ # ── L4 — attenuable capability tokens (agent JWT) ─────────────────
105
+ async def issue_capability(
106
+ self, agent_jwt: str, permissions: List[str],
107
+ *,
108
+ holder_agent_did: Optional[str] = None,
109
+ budget_total: Optional[float] = None,
110
+ currency: Optional[str] = None,
111
+ max_uses: Optional[int] = None,
112
+ ttl_seconds: Optional[int] = None,
113
+ caveats: Optional[Dict[str, Any]] = None,
114
+ ) -> Dict[str, Any]:
115
+ """
116
+ Mint a root `att_` capability token (requires the `authz.delegate`
117
+ meta-permission; `permissions` must be ⊆ your CURRENT authority).
118
+
119
+ `caveats` merges extra caveat fields (max_per_tx, allowed_currencies,
120
+ counterparty_allow, operations, no_redelegate, phone_* …).
121
+ `ttl_seconds` 60..86400 (server default 900). The response's `token`
122
+ is shown ONCE — store it; only the hash persists server-side.
123
+ """
124
+ body: Dict[str, Any] = {"caveats": self._caveats(permissions, caveats)}
125
+ if holder_agent_did is not None:
126
+ body["holder_agent_did"] = holder_agent_did
127
+ if budget_total is not None:
128
+ body["budget_total"] = budget_total
129
+ if currency is not None:
130
+ body["currency"] = currency
131
+ if max_uses is not None:
132
+ body["max_uses"] = max_uses
133
+ if ttl_seconds is not None:
134
+ body["ttl_seconds"] = ttl_seconds
135
+ resp = await self._get_client().post(
136
+ f"{self.base}/api/v1/agents/capabilities",
137
+ json=body, headers=self._auth(agent_jwt),
138
+ )
139
+ data = self._ok(resp)
140
+ logger.info(f"[AuthzClient] capability issued: id={data.get('id')} -> {holder_agent_did or 'bearer'}")
141
+ return data
142
+
143
+ async def attenuate(
144
+ self, agent_jwt: str, token_id: int, permissions: List[str],
145
+ *,
146
+ budget_total: Optional[float] = None,
147
+ max_uses: Optional[int] = None,
148
+ ttl_seconds: Optional[int] = None,
149
+ caveats: Optional[Dict[str, Any]] = None,
150
+ ) -> Dict[str, Any]:
151
+ """
152
+ Derive a strictly-weaker CHILD token from a token you hold (or issued).
153
+ Attenuation rides the TOKEN, not your role — no meta-permission needed;
154
+ the child can never exceed the parent (denied if the parent set
155
+ `no_redelegate`, or past the max chain depth of 3).
156
+ """
157
+ body: Dict[str, Any] = {"caveats": self._caveats(permissions, caveats)}
158
+ if budget_total is not None:
159
+ body["budget_total"] = budget_total
160
+ if max_uses is not None:
161
+ body["max_uses"] = max_uses
162
+ if ttl_seconds is not None:
163
+ body["ttl_seconds"] = ttl_seconds
164
+ resp = await self._get_client().post(
165
+ f"{self.base}/api/v1/agents/capabilities/{token_id}/attenuate",
166
+ json=body, headers=self._auth(agent_jwt),
167
+ )
168
+ return self._ok(resp)
169
+
170
+ async def my_capabilities(self, agent_jwt: str) -> Dict[str, Any]:
171
+ """
172
+ Capability tokens I issued or hold. Returns `{agent_did, mode, tokens:
173
+ [{id, role, issuer_did, holder_did, parent_token_id, depth, status,
174
+ permissions, budget_remaining, currency, expires_at}]}`.
175
+ """
176
+ resp = await self._get_client().get(
177
+ f"{self.base}/api/v1/agents/capabilities/mine",
178
+ headers=self._auth(agent_jwt),
179
+ )
180
+ return self._ok(resp)
181
+
182
+ async def revoke_capability(self, agent_jwt: str, token_id: int) -> Dict[str, Any]:
183
+ """
184
+ Revoke a token AND its whole subtree (issuer or holder only). Returns
185
+ `{ok, root_token_id, revoked_count}`.
186
+ """
187
+ resp = await self._get_client().delete(
188
+ f"{self.base}/api/v1/agents/capabilities/{token_id}",
189
+ headers=self._auth(agent_jwt),
190
+ )
191
+ data = self._ok(resp)
192
+ logger.info(f"[AuthzClient] revoked token {token_id} subtree: {data.get('revoked_count')} tokens")
193
+ return data
@@ -0,0 +1,202 @@
1
+ """
2
+ GÖDEL FORGE Client — the self-improving-harness arena.
3
+
4
+ A coding agent (harness) forks its own bundle, commits variant versions of its
5
+ code line, gets scored by an independent staked verifier quorum (never
6
+ self-reported), and adopts the winner — the full loop from agent code:
7
+
8
+ forge = ForgeClient("https://frame-c.theprotocol.cloud")
9
+ status = await forge.get_status() # {"enabled": False} on dark arenas
10
+ tree = await forge.get_lineage(org_id) # the Evolution Tree
11
+ child = await forge.fork_bundle(agent_jwt, bundle_id, royalty_bps=250)
12
+ ver = await forge.self_version(agent_jwt, "1.1.0", notes="variant 7")
13
+ await forge.run_eval(agent_jwt, suite_id=3) # quorum-scored, code_patch
14
+ await forge.activate_version(agent_jwt, ver["version_id"]) # adopt
15
+
16
+ The arena is registry-gated (FORGE_ENABLED): most registries run dark and
17
+ return 403 — `get_status()` surfaces that as `{"enabled": False}` instead of
18
+ raising, so probing a venue is cheap. Mutating calls raise ForgeDisabledError.
19
+
20
+ Permissions (IRONKEY, byte-inert while AGENT_RBAC_MODE=off): fork_bundle needs
21
+ `bundle.write`; self_version/activate_version need `cicd.version`; evaluating a
22
+ target other than yourself needs `forge.evolve_for_org`.
23
+ """
24
+ import logging
25
+ from typing import Any, Dict, Optional
26
+
27
+ import httpx
28
+
29
+ logger = logging.getLogger(__name__)
30
+
31
+
32
+ class ForgeError(RuntimeError):
33
+ """Raised on a non-2xx forge response. Carries the HTTP status and the
34
+ structured detail the registry returned."""
35
+
36
+ def __init__(self, status_code: int, detail: Any):
37
+ self.status_code = status_code
38
+ self.detail = detail
39
+ super().__init__(f"forge request failed ({status_code}): {str(detail)[:300]}")
40
+
41
+
42
+ class ForgeDisabledError(ForgeError):
43
+ """The arena is dark on this registry (FORGE_ENABLED off → 403)."""
44
+
45
+
46
+ class ForgeClient:
47
+ """Client for the GÖDEL FORGE arena endpoints on one registry."""
48
+
49
+ def __init__(self, registry_url: str, transport: Optional[httpx.AsyncBaseTransport] = None):
50
+ self.base = registry_url.rstrip("/")
51
+ self._client: Optional[httpx.AsyncClient] = None
52
+ self._transport = transport # test seam (httpx.MockTransport)
53
+
54
+ def _get_client(self) -> httpx.AsyncClient:
55
+ if self._client is None or self._client.is_closed:
56
+ self._client = httpx.AsyncClient(
57
+ transport=self._transport,
58
+ limits=httpx.Limits(max_connections=50, max_keepalive_connections=10),
59
+ timeout=httpx.Timeout(60.0, connect=5.0),
60
+ )
61
+ return self._client
62
+
63
+ async def close(self):
64
+ if self._client and not self._client.is_closed:
65
+ await self._client.aclose()
66
+ self._client = None
67
+
68
+ @staticmethod
69
+ def _auth(agent_jwt: str) -> Dict[str, str]:
70
+ return {"Authorization": f"Bearer {agent_jwt}"}
71
+
72
+ @staticmethod
73
+ def _detail(resp: httpx.Response) -> Any:
74
+ try:
75
+ return resp.json().get("detail", resp.text)
76
+ except Exception:
77
+ return resp.text[:300]
78
+
79
+ def _raise(self, resp: httpx.Response) -> None:
80
+ detail = self._detail(resp)
81
+ if resp.status_code == 403 and "FORGE_ENABLED" in str(detail):
82
+ raise ForgeDisabledError(resp.status_code, detail)
83
+ raise ForgeError(resp.status_code, detail)
84
+
85
+ # ── arena reads (public) ──────────────────────────────────────────
86
+ async def get_status(self) -> Dict[str, Any]:
87
+ """
88
+ Arena status + flags + known lineages.
89
+
90
+ Returns the server dict (`{"enabled": True, "lineages": [...], "flags":
91
+ {...}, "counts": {...}}`) when the arena is live. A dark arena (403 —
92
+ FORGE_ENABLED off, the fleet default) is a normal state, not an error:
93
+ returns `{"enabled": False, "detail": <server detail>}`.
94
+ """
95
+ resp = await self._get_client().get(f"{self.base}/api/v1/forge/status")
96
+ if resp.status_code == 200:
97
+ return resp.json()
98
+ if resp.status_code == 403:
99
+ return {"enabled": False, "detail": self._detail(resp)}
100
+ self._raise(resp)
101
+
102
+ async def get_lineage(self, org_id: str) -> Dict[str, Any]:
103
+ """
104
+ Evolution Tree for a lineage (org): roster ∪ spawn kinship ∪ bundle
105
+ fork graph ∪ eval scores. Returns `{org_id, nodes, edges, agent_count,
106
+ bundle_count}`. Raises ForgeDisabledError on a dark arena.
107
+ """
108
+ resp = await self._get_client().get(f"{self.base}/api/v1/forge/lineages/{org_id}")
109
+ if resp.status_code == 200:
110
+ return resp.json()
111
+ self._raise(resp)
112
+
113
+ # ── the self-improvement loop (agent JWT) ─────────────────────────
114
+ async def run_eval(self, agent_jwt: str, suite_id: int,
115
+ target_did: Optional[str] = None) -> Dict[str, Any]:
116
+ """
117
+ Trigger an eval-suite run against yourself (default) or `target_did`
118
+ (requires the `forge.evolve_for_org` delegation). Scores settle via the
119
+ runner — code_patch suites go through the verifier quorum, never
120
+ self-reported. Returns `{suite_id, target_did, run_id, status}`.
121
+ """
122
+ body: Dict[str, Any] = {"suite_id": suite_id}
123
+ if target_did is not None:
124
+ body["target_did"] = target_did
125
+ resp = await self._get_client().post(
126
+ f"{self.base}/api/v1/forge/evals/run", json=body, headers=self._auth(agent_jwt),
127
+ )
128
+ if resp.status_code == 200:
129
+ return resp.json()
130
+ self._raise(resp)
131
+
132
+ async def fork_bundle(self, agent_jwt: str, bundle_id: str,
133
+ royalty_bps: Optional[int] = None,
134
+ name: Optional[str] = None,
135
+ description: Optional[str] = None) -> Dict[str, Any]:
136
+ """
137
+ Fork a bundle as an agent (permission `bundle.write`): restore-with-rename
138
+ of the parent, fork lineage stamped (`forked_from_bundle_id`), optional
139
+ `royalty_bps` (0-500) carved up the lineage on future eval payouts.
140
+ The child stays in the parent's lineage org.
141
+ """
142
+ body: Dict[str, Any] = {}
143
+ if name is not None:
144
+ body["name"] = name
145
+ if description is not None:
146
+ body["description"] = description
147
+ if royalty_bps is not None:
148
+ body["royalty_bps"] = royalty_bps
149
+ resp = await self._get_client().post(
150
+ f"{self.base}/api/v1/agents/bundles/{bundle_id}/fork",
151
+ json=body, headers=self._auth(agent_jwt),
152
+ )
153
+ if resp.status_code == 200:
154
+ return resp.json()
155
+ self._raise(resp)
156
+
157
+ async def self_version(self, agent_jwt: str, version: str,
158
+ artifacts: Optional[Dict[str, Any]] = None,
159
+ notes: Optional[str] = None,
160
+ commit_hash: Optional[str] = None,
161
+ is_stable: Optional[bool] = None) -> Dict[str, Any]:
162
+ """
163
+ Commit a NEW VERSION of your own code line (permission `cicd.version`) —
164
+ no developer-JWT round-trip. `notes` maps to the registry's
165
+ `release_notes` field.
166
+
167
+ The registry keys the created row as `version_id` (NOT `id`); this
168
+ method guarantees `result["version_id"]` is present.
169
+ """
170
+ body: Dict[str, Any] = {"version": version}
171
+ if commit_hash is not None:
172
+ body["commit_hash"] = commit_hash
173
+ if notes is not None:
174
+ body["release_notes"] = notes
175
+ if artifacts is not None:
176
+ body["artifacts"] = artifacts
177
+ if is_stable is not None:
178
+ body["is_stable"] = is_stable
179
+ resp = await self._get_client().post(
180
+ f"{self.base}/api/v1/agents/self/version",
181
+ json=body, headers=self._auth(agent_jwt),
182
+ )
183
+ if resp.status_code == 200:
184
+ data = resp.json()
185
+ if "version_id" not in data and "id" in data:
186
+ data["version_id"] = data["id"] # normalize — callers rely on version_id
187
+ logger.info(f"[ForgeClient] version committed: {version} -> {data.get('version_id')}")
188
+ return data
189
+ self._raise(resp)
190
+
191
+ async def activate_version(self, agent_jwt: str, version_id: str) -> Dict[str, Any]:
192
+ """
193
+ ADOPT a variant: activate one of your OWN versions (permission
194
+ `cicd.version`), completing the commit → eval → adopt loop.
195
+ """
196
+ resp = await self._get_client().post(
197
+ f"{self.base}/api/v1/agents/self/versions/{version_id}/activate",
198
+ headers=self._auth(agent_jwt),
199
+ )
200
+ if resp.status_code == 200:
201
+ return resp.json()
202
+ self._raise(resp)