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.
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/.gitignore +29 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/PKG-INFO +54 -6
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/README.md +50 -2
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/pyproject.toml +11 -4
- theprotocol_sdk-0.6.2/src/theprotocol/__init__.py +16 -0
- theprotocol_sdk-0.6.2/src/theprotocol/authz.py +193 -0
- theprotocol_sdk-0.6.2/src/theprotocol/forge.py +202 -0
- theprotocol_sdk-0.6.2/src/theprotocol/guild.py +211 -0
- theprotocol_sdk-0.6.2/src/theprotocol/mtls.py +337 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/registry/__init__.py +3 -0
- theprotocol_sdk-0.6.2/src/theprotocol/registry/card_verify.py +142 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/registry/cost_composition.py +4 -2
- theprotocol_sdk-0.6.2/tests/registry/test_card_verify.py +170 -0
- theprotocol_sdk-0.6.2/tests/test_authz.py +142 -0
- theprotocol_sdk-0.6.2/tests/test_forge.py +197 -0
- theprotocol_sdk-0.6.2/tests/test_guild.py +186 -0
- theprotocol_sdk-0.6.2/tests/test_mtls_enroll.py +270 -0
- theprotocol_sdk-0.5.1/src/theprotocol/__init__.py +0 -11
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/LICENSE +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/examples/simple_agent.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/agent/__init__.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/agent/base.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/agent/decorators.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/agent/router.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/agent/task_store.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/agent/well_known.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/auth/__init__.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/auth/did_jwt.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/auth/jws_card.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/auth/jwt_verifier.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/bridges/__init__.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/bridges/acp.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/bridges/anp/__init__.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/bridges/anp/auth.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/bridges/anp/bridge.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/bridges/anp/did_wba.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/bridges/anp/translation.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/bridges/base.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/bridges/google_a2a.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/bridges/mcp.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/client/__init__.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/client/a2a_client.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/client/credentials.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/exceptions.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/exchange/__init__.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/exchange/client.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/models/__init__.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/models/a2a_protocol.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/models/agent_card.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/models/v1_compat.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/payment/__init__.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/payment/authenticator.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/payment/client.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/payment/mtls_client.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/payment/verifier.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/transfer/__init__.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/src/theprotocol/transfer/client.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/registry/__init__.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/registry/test_cost_composition.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_agent.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_artifact_roundtrip.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_auth.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_bridge_acp.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_bridge_anp.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_bridge_google_a2a.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_bridge_mcp.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_credentials.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_did_jwt.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_jws_card.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_models.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_transfer.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_v1_compat.py +0 -0
- {theprotocol_sdk-0.5.1 → theprotocol_sdk-0.6.2}/tests/test_verifier_reuse.py +0 -0
- {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.
|
|
4
|
-
Summary:
|
|
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://
|
|
7
|
-
Project-URL:
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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.
|
|
8
|
-
description = "
|
|
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://
|
|
48
|
-
|
|
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)
|