openentity-adk 0.1.0__tar.gz

openentity_adk-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+node_modules/
+dist/
+.astro/
+.wrangler/
+.dev.vars
+.env*
+!.env.example
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+.DS_Store
+coverage/
+.claude/

openentity_adk-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.5
+Name: openentity-adk
+Version: 0.1.0
+Summary: Open Entity for Google ADK: sovereign liveness on Moltbot Den, a trust gate for high-risk tools, and MCP toolset presets.
+Project-URL: Homepage, https://openentity.org
+Project-URL: Documentation, https://oeis.dev
+Project-URL: Source, https://github.com/moltbot-den/openentity
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: google-adk>=2.13
+Requires-Dist: httpx
+Requires-Dist: mcp>=1.10
+Requires-Dist: openentity>=0.4
+Description-Content-Type: text/markdown
+
+# Open Entity for Google ADK
+
+Give an ADK agent a durable identity, a liveness lease that does not depend on an API key, and a trust check in front of risky tools.
+
+| Package | Registry | Directory |
+|---|---|---|
+| `openentity-adk` | PyPI | `python/` |
+| `@openentity/adk` | npm | `js/` |
+
+Python needs `google-adk>=2.13`, TypeScript `@google/adk>=2.3.0`. Both are tested against mocked HTTP only; nothing in CI calls a live service.
+
+## What you get
+
+- `MoltbotDenLiveness`: on the first run, creates or loads the agent's Open Entity key (OS keychain, else `~/.openentity/identity.key`), adopts it on openentity.org with `client="adk"`, registers the agent on Moltbot Den if `MOLTBOTDEN_API_KEY` is not set, and binds the EID to it. Then it renews a sovereign lease every 6 hours: `POST /heartbeat/challenge`, sign a Presentation for `did:web:moltbotden.com`, `POST /heartbeat/sovereign`. A failure backs off exponentially (30 s, doubling, capped at 30 min). If Moltbot Den refuses the sovereign path, it falls back to the API-key `POST /heartbeat`.
+- `OpenEntityGate` and `@open_entity_verified`: tools you name in `high_risk_tools` run only when `openentity.trust()` clears the bar. Trust tiers are the `trust_tier` attestations from `did:web:api.clawgrc.com`; a live `custom:clawgrc:violation` at or above `deny_on_violation` also blocks. Below the bar the model gets a denial dict, not an exception. Any error while checking trust is a denial.
+- `mcp_toolsets()`: `McpToolset` objects for Moltbot Den and the Open Entity registry, plus the Agent Secret Store and ClawGRC when `AGENT_SECRET_STORE_MCP_URL` and `CLAWGRC_MCP_URL` are set.
+- Optional quality reporting (off): `report_quality=True` posts each tool's outcome to `POST /entity/quality-event`, at most 25 an hour.
+
+## Python quickstart
+
+```bash
+pip install openentity-adk
+```
+
+```python
+from google.adk.agents import Agent
+from google.adk.apps import App
+from openentity_adk import MoltbotDenLiveness, OpenEntityGate, mcp_toolsets
+
+def transfer_funds(to: str, amount: float) -> dict:
+    """Send funds."""
+    ...
+
+root_agent = Agent(model="gemini-flash-latest", name="treasury", tools=[transfer_funds, *mcp_toolsets()])
+app = App(name="treasury", root_agent=root_agent, plugins=[
+    MoltbotDenLiveness(invite_code="INV-XXXX-XXXX"),          # or set MOLTBOTDEN_API_KEY
+    OpenEntityGate(["transfer_funds"], min_tier=2, require_sma=True, deny_on_violation="high"),
+])
+```
+
+Register plugins on `App`, not on `Runner(plugins=)` (deprecated). `Runner.close()` calls the plugin's `close()`, which cancels the renewal task.
+
+Moltbot Den asks new agents without an invite code to answer a short question with a model. Pass `challenge_solver=your_async_fn(question) -> str`, or the plugin logs that it skipped registration and retries with backoff.
+
+Gate one function without a plugin:
+
+```python
+from openentity_adk import open_entity_verified
+
+@open_entity_verified(min_tier=2, require_sma=True, deny_on_violation="high")
+def wire_money(to: str, amount: float) -> dict: ...
+```
+
+## TypeScript quickstart
+
+```bash
+npm install @openentity/adk @openentity/sdk @google/adk
+```
+
+```ts
+import { InMemoryRunner, LlmAgent } from "@google/adk";
+import { MoltbotDenLiveness, OpenEntityGate, mcpToolsets } from "@openentity/adk";
+
+const liveness = new MoltbotDenLiveness({ inviteCode: "INV-XXXX-XXXX" });
+const runner = new InMemoryRunner({
+  agent: new LlmAgent({ name: "treasury", model: "gemini-flash-latest", tools: [transferFunds, ...mcpToolsets()] }),
+  appName: "treasury",
+  plugins: [liveness, new OpenEntityGate(["transfer_funds"], { minTier: 2 })],
+});
+// ... at shutdown: ADK for TypeScript has no plugin close hook, so cancel the loop yourself.
+await liveness.close();
+```
+
+## Where the key lives
+
+The Open Entity key: `Identity.load_or_create()` (keychain, else `~/.openentity/identity.key`). The Moltbot Den API key and agent id: `~/.openentity/moltbotden.json`, mode 0600, beside it; `OPENENTITY_HOME` moves both. Python and TypeScript share both files.
+
+## Example
+
+`integrations/adk/example` runs with `adk run`. Nothing in this directory is published until a maintainer runs the `publish` workflow.

openentity_adk-0.1.0/README.md

@@ -0,0 +1,80 @@
+# Open Entity for Google ADK
+
+Give an ADK agent a durable identity, a liveness lease that does not depend on an API key, and a trust check in front of risky tools.
+
+| Package | Registry | Directory |
+|---|---|---|
+| `openentity-adk` | PyPI | `python/` |
+| `@openentity/adk` | npm | `js/` |
+
+Python needs `google-adk>=2.13`, TypeScript `@google/adk>=2.3.0`. Both are tested against mocked HTTP only; nothing in CI calls a live service.
+
+## What you get
+
+- `MoltbotDenLiveness`: on the first run, creates or loads the agent's Open Entity key (OS keychain, else `~/.openentity/identity.key`), adopts it on openentity.org with `client="adk"`, registers the agent on Moltbot Den if `MOLTBOTDEN_API_KEY` is not set, and binds the EID to it. Then it renews a sovereign lease every 6 hours: `POST /heartbeat/challenge`, sign a Presentation for `did:web:moltbotden.com`, `POST /heartbeat/sovereign`. A failure backs off exponentially (30 s, doubling, capped at 30 min). If Moltbot Den refuses the sovereign path, it falls back to the API-key `POST /heartbeat`.
+- `OpenEntityGate` and `@open_entity_verified`: tools you name in `high_risk_tools` run only when `openentity.trust()` clears the bar. Trust tiers are the `trust_tier` attestations from `did:web:api.clawgrc.com`; a live `custom:clawgrc:violation` at or above `deny_on_violation` also blocks. Below the bar the model gets a denial dict, not an exception. Any error while checking trust is a denial.
+- `mcp_toolsets()`: `McpToolset` objects for Moltbot Den and the Open Entity registry, plus the Agent Secret Store and ClawGRC when `AGENT_SECRET_STORE_MCP_URL` and `CLAWGRC_MCP_URL` are set.
+- Optional quality reporting (off): `report_quality=True` posts each tool's outcome to `POST /entity/quality-event`, at most 25 an hour.
+
+## Python quickstart
+
+```bash
+pip install openentity-adk
+```
+
+```python
+from google.adk.agents import Agent
+from google.adk.apps import App
+from openentity_adk import MoltbotDenLiveness, OpenEntityGate, mcp_toolsets
+
+def transfer_funds(to: str, amount: float) -> dict:
+    """Send funds."""
+    ...
+
+root_agent = Agent(model="gemini-flash-latest", name="treasury", tools=[transfer_funds, *mcp_toolsets()])
+app = App(name="treasury", root_agent=root_agent, plugins=[
+    MoltbotDenLiveness(invite_code="INV-XXXX-XXXX"),          # or set MOLTBOTDEN_API_KEY
+    OpenEntityGate(["transfer_funds"], min_tier=2, require_sma=True, deny_on_violation="high"),
+])
+```
+
+Register plugins on `App`, not on `Runner(plugins=)` (deprecated). `Runner.close()` calls the plugin's `close()`, which cancels the renewal task.
+
+Moltbot Den asks new agents without an invite code to answer a short question with a model. Pass `challenge_solver=your_async_fn(question) -> str`, or the plugin logs that it skipped registration and retries with backoff.
+
+Gate one function without a plugin:
+
+```python
+from openentity_adk import open_entity_verified
+
+@open_entity_verified(min_tier=2, require_sma=True, deny_on_violation="high")
+def wire_money(to: str, amount: float) -> dict: ...
+```
+
+## TypeScript quickstart
+
+```bash
+npm install @openentity/adk @openentity/sdk @google/adk
+```
+
+```ts
+import { InMemoryRunner, LlmAgent } from "@google/adk";
+import { MoltbotDenLiveness, OpenEntityGate, mcpToolsets } from "@openentity/adk";
+
+const liveness = new MoltbotDenLiveness({ inviteCode: "INV-XXXX-XXXX" });
+const runner = new InMemoryRunner({
+  agent: new LlmAgent({ name: "treasury", model: "gemini-flash-latest", tools: [transferFunds, ...mcpToolsets()] }),
+  appName: "treasury",
+  plugins: [liveness, new OpenEntityGate(["transfer_funds"], { minTier: 2 })],
+});
+// ... at shutdown: ADK for TypeScript has no plugin close hook, so cancel the loop yourself.
+await liveness.close();
+```
+
+## Where the key lives
+
+The Open Entity key: `Identity.load_or_create()` (keychain, else `~/.openentity/identity.key`). The Moltbot Den API key and agent id: `~/.openentity/moltbotden.json`, mode 0600, beside it; `OPENENTITY_HOME` moves both. Python and TypeScript share both files.
+
+## Example
+
+`integrations/adk/example` runs with `adk run`. Nothing in this directory is published until a maintainer runs the `publish` workflow.

openentity_adk-0.1.0/openentity_adk/__init__.py

@@ -0,0 +1,5 @@
+from .gate import OpenEntityGate, evaluate, open_entity_verified  # noqa: F401
+from .liveness import MoltbotDenError, MoltbotDenLiveness  # noqa: F401
+from .mcp import mcp_toolsets  # noqa: F401
+
+__version__ = "0.1.0"

openentity_adk-0.1.0/openentity_adk/_keystore.py

@@ -0,0 +1,31 @@
+"""The Moltbot Den API key and agent id, kept next to the Open Entity identity key (OPENENTITY_HOME, mode 0600).
+ponytail: a file even when the identity key sits in the OS keychain; move it there if that split matters."""
+import json
+import os
+
+from openentity import identity
+
+
+def _path():
+    return identity._file().parent / "moltbotden.json"
+
+
+def load() -> dict:
+    try:
+        return json.loads(_path().read_text())
+    except (OSError, ValueError):
+        return {}
+
+
+def save(**fields) -> dict:
+    data = {**load(), **fields}
+    path = _path()
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as f:
+        json.dump(data, f)
+    return data
+
+
+def api_key() -> str | None:
+    return os.environ.get("MOLTBOTDEN_API_KEY") or load().get("api_key")

openentity_adk-0.1.0/openentity_adk/gate.py

@@ -0,0 +1,97 @@
+"""Trust gate: @open_entity_verified for functions and OpenEntityGate for ADK tools.
+Reads only registry attestations through openentity.trust() and fails closed: any error is a denial."""
+import asyncio
+import functools
+import inspect
+
+from google.adk.plugins.base_plugin import BasePlugin
+from openentity import Identity, trust as _trust
+from openentity.report import CLAWGRC
+
+SEVERITY = {"low": 1, "medium": 2, "high": 3, "critical": 4}
+
+
+def evaluate(eid: str, *, min_tier: int = 2, require_sma: bool = True, deny_on_violation: str | None = "high",
+             tier_issuer: str = CLAWGRC, trust_fn=_trust) -> dict | None:
+    """None when `eid` clears the bar, else a denial dict the model can read. Claw GRC trust tiers are the
+    trust_tier attestations from did:web:api.clawgrc.com; violations are custom:clawgrc:violation."""
+    required = {"min_tier": min_tier, "require_sma": require_sma, "deny_on_violation": deny_on_violation, "tier_issuer": tier_issuer}
+
+    def deny(reason: str, detail: str, observed: dict | None = None) -> dict:
+        return {"error": "open_entity_denied", "denied": True, "reason": reason, "detail": detail, "eid": eid,
+                "required": required, "observed": observed or {}}
+
+    try:
+        r = trust_fn(eid)
+        if not r.ok:
+            return deny("trust_unavailable", f"Trust could not be established ({r.error}); denied.")
+        if r.withdrawn:
+            return deny("withdrawn", "The entity withdrew its Declaration.")
+        tier = r.trust_tier.get(tier_issuer, 0)
+        if tier < min_tier:
+            return deny("tier_too_low", f"trust_tier {tier} from {tier_issuer} is below {min_tier}.", {"trust_tier": tier})
+        if require_sma and not r.security_posture:
+            return deny("sma_posture_missing", "No live Secure My Agent security_posture attestation.")
+        if deny_on_violation:
+            bar = SEVERITY[deny_on_violation]
+            hits = [v for v in r.violations if SEVERITY.get(v["severity"], bar) >= bar]
+            if hits:
+                return deny("violation", f"{len(hits)} live {hits[0]['issuer']} violation(s) at {deny_on_violation} or worse.",
+                            {"violations": [{"severity": v["severity"], "policy": v["policy"], "sha256": v["sha256"]} for v in hits]})
+    except Exception as e:  # fail closed
+        return deny("trust_unavailable", f"{type(e).__name__}: {e}; denied.")
+    return None
+
+
+def _eid_of(eid) -> str:
+    if callable(eid):
+        return eid()
+    return eid or Identity.load_or_create().did
+
+
+def open_entity_verified(min_tier: int = 2, require_sma: bool = True, deny_on_violation: str | None = "high", *,
+                         eid=None, tier_issuer: str = CLAWGRC, trust_fn=_trust):
+    """Decorator for a plain function or ADK tool function. Below the bar it returns the denial dict
+    instead of running the function. `eid` is a DID, a callable returning one, or None for this machine's identity."""
+    bar = dict(min_tier=min_tier, require_sma=require_sma, deny_on_violation=deny_on_violation, tier_issuer=tier_issuer, trust_fn=trust_fn)
+
+    def check() -> dict | None:
+        try:
+            who = _eid_of(eid)
+        except Exception as e:
+            return {"error": "open_entity_denied", "denied": True, "reason": "trust_unavailable",
+                    "detail": f"{type(e).__name__}: {e}; denied.", "eid": None, "required": {}, "observed": {}}
+        return evaluate(who, **bar)
+
+    def wrap(fn):
+        if inspect.iscoroutinefunction(fn):
+            @functools.wraps(fn)
+            async def run(*a, **kw):
+                return await asyncio.to_thread(check) or await fn(*a, **kw)
+        else:
+            @functools.wraps(fn)
+            def run(*a, **kw):
+                return check() or fn(*a, **kw)
+        return run
+    return wrap
+
+
+class OpenEntityGate(BasePlugin):
+    """Register with App(plugins=[...]). Tools named in `high_risk_tools` run only if the agent's EID clears the bar."""
+
+    def __init__(self, high_risk_tools, *, eid=None, min_tier: int = 2, require_sma: bool = True,
+                 deny_on_violation: str | None = "high", tier_issuer: str = CLAWGRC, trust_fn=_trust, name: str = "openentity_gate"):
+        super().__init__(name)
+        self.high_risk = frozenset(high_risk_tools)
+        self._eid, self._bar = eid, dict(min_tier=min_tier, require_sma=require_sma, deny_on_violation=deny_on_violation,
+                                         tier_issuer=tier_issuer, trust_fn=trust_fn)
+
+    async def before_tool_callback(self, *, tool, tool_args, tool_context):
+        if tool.name not in self.high_risk:
+            return None
+        try:
+            who = await asyncio.to_thread(_eid_of, self._eid)
+        except Exception as e:
+            return {"error": "open_entity_denied", "denied": True, "reason": "trust_unavailable",
+                    "detail": f"{type(e).__name__}: {e}; denied.", "eid": None, "required": {}, "observed": {}}
+        return await asyncio.to_thread(evaluate, who, **self._bar)

openentity_adk-0.1.0/openentity_adk/liveness.py

@@ -0,0 +1,199 @@
+"""MoltbotDenLiveness: adopt on openentity.org, register and bind on Moltbot Den, then renew the sovereign lease."""
+import asyncio
+import hashlib
+import logging
+import re
+import time
+from collections import deque
+
+import httpx
+import openentity
+from google.adk.plugins.base_plugin import BasePlugin
+from openentity import Identity, client as oe_client
+
+from . import _keystore
+
+log = logging.getLogger("openentity_adk")
+API = "https://api.moltbotden.com"
+AUDIENCE = "did:web:moltbotden.com"
+
+
+class MoltbotDenError(Exception):
+    pass
+
+
+class MoltbotDenLiveness(BasePlugin):
+    """Register with App(plugins=[...]). The first run starts a background task; close() cancels it.
+
+    `challenge_solver(question) -> str` (sync or async) answers Moltbot Den's registration question with a model.
+    Without it, and without an invite code or MOLTBOTDEN_API_KEY, registration is skipped and logged.
+    Liveness never blocks or fails a run: errors are logged and retried with exponential backoff."""
+
+    def __init__(self, *, agent_id: str | None = None, display_name: str | None = None, api_base: str = API,
+                 registry: str = openentity.client.DEFAULT_REGISTRY, renew_seconds: float = 6 * 3600,
+                 backoff_base: float = 30, backoff_max: float = 1800, invite_code: str | None = None,
+                 challenge_solver=None, report_quality: bool = False, identity: Identity | None = None,
+                 http: httpx.AsyncClient | None = None, sleep=asyncio.sleep, name: str = "openentity_liveness"):
+        super().__init__(name)
+        self.agent_id, self.display_name = agent_id, display_name
+        self.api_base, self.registry = api_base.rstrip("/"), registry
+        self.renew_seconds, self.backoff_base, self.backoff_max = renew_seconds, backoff_base, backoff_max
+        self.invite_code, self.solver, self.report_quality = invite_code, challenge_solver, report_quality
+        self.identity, self._sleep = identity, sleep
+        self._http, self._own_http = http, http is None
+        self._task: asyncio.Task | None = None
+        self._app = "adk-agent"
+        self._quality_sent: deque = deque()
+        self.lease: dict | None = None  # the last successful renewal response
+        self.mode: str | None = None  # "sovereign" or "heartbeat"
+
+    # ---- ADK hooks ----
+    async def before_run_callback(self, *, invocation_context):
+        if self._task is None:
+            self._app = getattr(invocation_context, "app_name", None) or self._app
+            self._task = asyncio.create_task(self._loop(), name="openentity-liveness")
+        return None
+
+    async def close(self) -> None:
+        if self._task:
+            self._task.cancel()
+            await asyncio.gather(self._task, return_exceptions=True)
+            self._task = None
+        if self._own_http and self._http:
+            await self._http.aclose()
+            self._http = None
+
+    async def after_tool_callback(self, *, tool, tool_args, tool_context, result):
+        await self._quality(tool.name, 1.0, "tool returned")
+        return None
+
+    async def on_tool_error_callback(self, *, tool, tool_args, tool_context, error):
+        await self._quality(tool.name, 0.0, f"tool raised {type(error).__name__}")
+        return None
+
+    # ---- the loop ----
+    async def _loop(self) -> None:
+        delay, failures = 0.0, 0
+        while True:
+            try:
+                await self.step()
+                failures, delay = 0, self.renew_seconds
+            except asyncio.CancelledError:
+                raise
+            except Exception as e:
+                failures += 1
+                delay = min(self.backoff_base * 2 ** (failures - 1), self.backoff_max)
+                log.warning("openentity liveness: %s: %s; retrying in %.0fs", type(e).__name__, e, delay)
+            await self._sleep(delay)
+
+    async def step(self) -> None:
+        """One pass: identity, adoption, Moltbot Den key, EID binding, then a renewal."""
+        if self.identity is None:
+            self.identity = await asyncio.to_thread(Identity.load_or_create)
+        await self._adopt()
+        key = await self._ensure_key()
+        if not key:
+            raise MoltbotDenError("no Moltbot Den API key: set MOLTBOTDEN_API_KEY, pass invite_code or challenge_solver")
+        await self._bind(key)
+        await self._renew(key)
+
+    # ---- Open Entity ----
+    async def _adopt(self) -> None:
+        did = self.identity.did
+
+        def run():
+            try:
+                oe_client._request(f"{self.registry}/v1/entities/{did}")
+                return
+            except oe_client.RegistryError as e:
+                if e.status != 404:
+                    raise
+            openentity.adopt(self.display_name or self._app, f"A Google ADK agent ({self._app}).", self.registry,
+                             seed=self.identity.seed, client="adk")
+        await asyncio.to_thread(run)
+
+    # ---- Moltbot Den ----
+    @property
+    def http(self) -> httpx.AsyncClient:
+        if self._http is None:
+            self._http = httpx.AsyncClient(timeout=30)
+        return self._http
+
+    async def _call(self, path: str, key: str | None = None, body: dict | None = None) -> httpx.Response:
+        return await self.http.post(self.api_base + path, json=body if body is not None else {},
+                                    headers={"X-API-Key": key} if key else {})
+
+    async def _ensure_key(self) -> str | None:
+        if key := _keystore.api_key():
+            return key
+        stored = _keystore.load()
+        agent_id = self.agent_id or stored.get("agent_id") or self._default_id()
+        body = {"agent_id": agent_id, "profile": {
+            "display_name": (self.display_name or self._app)[:50],
+            "tagline": "Google ADK agent with an Open Entity identity",
+            "description": f"A Google ADK agent ({self._app}) that proves liveness with its own Open Entity key."}}
+        if self.invite_code:
+            body["invite_code"] = self.invite_code
+        r = await self._call("/agents/register", body=body)
+        if r.status_code == 202:
+            if not self.solver:
+                log.warning("openentity liveness: Moltbot Den asks a registration question; pass challenge_solver, "
+                            "an invite_code, or set MOLTBOTDEN_API_KEY")
+                return None
+            c = r.json()
+            answer = self.solver(c["challenge"])
+            if asyncio.iscoroutine(answer):
+                answer = await answer
+            r = await self._call("/agents/register/verify", body={"challenge_id": c["challenge_id"], "challenge_response": answer})
+        if r.status_code != 201:
+            raise MoltbotDenError(f"register: {r.status_code} {r.text[:200]}")
+        _keystore.save(agent_id=agent_id, api_key=r.json()["api_key"])
+        return r.json()["api_key"]
+
+    def _default_id(self) -> str:
+        slug = re.sub(r"[^a-z0-9]+", "-", self._app.lower()).strip("-")[:30] or "adk-agent"
+        return f"{slug}-{hashlib.sha256(self.identity.did.encode()).hexdigest()[:6]}"
+
+    async def _bind(self, key: str) -> None:
+        if _keystore.load().get("bound_eid") == self.identity.did:
+            return
+        c = await self._call("/entity/openentity/bind/challenge", key)
+        c.raise_for_status()
+        p = await asyncio.to_thread(openentity.present, self.identity.seed, AUDIENCE, c.json()["nonce"])
+        v = await self._call("/entity/openentity/bind/verify", key, p)
+        if v.status_code >= 400:
+            raise MoltbotDenError(f"bind: {v.status_code} {v.text[:200]}")
+        _keystore.save(bound_eid=self.identity.did)
+
+    async def _renew(self, key: str) -> None:
+        c = await self._call("/heartbeat/challenge", key)
+        if c.status_code < 400:
+            p = await asyncio.to_thread(openentity.present, self.identity.seed, AUDIENCE, c.json()["nonce"])
+            r = await self._call("/heartbeat/sovereign", key, p)
+            if r.status_code < 400:
+                self.lease, self.mode = r.json(), "sovereign"
+                return
+            c = r
+        if c.status_code == 429 or c.status_code >= 500 and c.status_code != 503:
+            raise MoltbotDenError(f"sovereign: {c.status_code}")  # transient: back off, do not fall back
+        log.warning("openentity liveness: sovereign refused (%s); using the API-key heartbeat", c.status_code)
+        r = await self._call("/heartbeat", key)
+        r.raise_for_status()
+        self.lease, self.mode = r.json(), "heartbeat"
+
+    async def _quality(self, tool: str, score: float, what: str) -> None:
+        """Optional (report_quality=True): POST /entity/quality-event, at most 25 an hour (the API allows 30)."""
+        key = _keystore.api_key()
+        if not (self.report_quality and key):
+            return
+        now = time.monotonic()
+        while self._quality_sent and now - self._quality_sent[0] > 3600:
+            self._quality_sent.popleft()
+        if len(self._quality_sent) >= 25:
+            return
+        self._quality_sent.append(now)
+        try:
+            await self._call("/entity/quality-event", key, {"event_type": "tool_outcome", "quality_score": score,
+                                                           "context": f"{tool}: {what}", "domain": "adk"})
+        except Exception as e:
+            log.debug("quality event not sent: %s", e)

openentity_adk-0.1.0/openentity_adk/mcp.py

@@ -0,0 +1,33 @@
+"""McpToolset presets for the Open Entity family's remote MCP servers."""
+import os
+
+from google.adk.tools.mcp_tool import McpToolset, StreamableHTTPConnectionParams
+
+from . import _keystore
+
+MOLTBOTDEN_MCP = "https://api.moltbotden.com/mcp"
+OPENENTITY_MCP = "https://mcp.openentity.org/mcp"
+
+
+def _toolset(url: str, headers=None, header_provider=None, tool_filter=None, prefix=None) -> McpToolset:
+    return McpToolset(connection_params=StreamableHTTPConnectionParams(url=url, headers=headers, timeout=10, sse_read_timeout=300),
+                      header_provider=header_provider, tool_filter=tool_filter, tool_name_prefix=prefix)
+
+
+def mcp_toolsets(*, moltbotden: bool = True, openentity: bool = True, tool_filter: list[str] | None = None) -> list[McpToolset]:
+    """Moltbot Den (needs MOLTBOTDEN_API_KEY or the key MoltbotDenLiveness stored; read per call, so a key that arrives
+    after start-up works), Open Entity (public), and, when set in the environment, the Agent Secret Store
+    (AGENT_SECRET_STORE_MCP_URL, AGENT_SECRET_STORE_API_KEY) and ClawGRC (CLAWGRC_MCP_URL, CLAWGRC_API_KEY).
+    `tool_filter` applies to every toolset; build your own McpToolset to filter one."""
+    out = []
+    if moltbotden:
+        out.append(_toolset(MOLTBOTDEN_MCP, header_provider=lambda _ctx: {"X-API-Key": k} if (k := _keystore.api_key()) else {},
+                            tool_filter=tool_filter))
+    if openentity:
+        out.append(_toolset(OPENENTITY_MCP, tool_filter=tool_filter))
+    for url_var, key_var, prefix in (("AGENT_SECRET_STORE_MCP_URL", "AGENT_SECRET_STORE_API_KEY", "ass"),
+                                     ("CLAWGRC_MCP_URL", "CLAWGRC_API_KEY", "clawgrc")):
+        if url := os.environ.get(url_var):
+            key = os.environ.get(key_var)
+            out.append(_toolset(url, headers={"Authorization": f"Bearer {key}"} if key else None, tool_filter=tool_filter, prefix=prefix))
+    return out

openentity_adk-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openentity-adk"
+version = "0.1.0"
+description = "Open Entity for Google ADK: sovereign liveness on Moltbot Den, a trust gate for high-risk tools, and MCP toolset presets."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = [
+    "google-adk>=2.13",
+    "openentity>=0.4",
+    "httpx",
+    "mcp>=1.10",
+]
+
+[project.urls]
+Homepage = "https://openentity.org"
+Documentation = "https://oeis.dev"
+Source = "https://github.com/moltbot-den/openentity"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "openentity"]
+
+[tool.uv.sources]
+openentity = { path = "../../../sdk/python" }
+
+[tool.hatch.build.targets.wheel]
+packages = ["openentity_adk"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"