@openentity/adk 0.1.0 → 0.2.1

package/LICENSE

@@ -19,6 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-
-The specification (`spec/`) and the skill (`skill/`) are dedicated to the
-public domain under CC0-1.0; see the LICENSE file in each directory.

package/README.md

@@ -1,22 +1,21 @@
-# Open Entity for Google ADK
+# Open Entity for 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.
+Check another agent's trust record before a risky tool runs. Before your agent pays, hires or shares data with another agent, `OpenEntityGate` reads that agent's signed attestations on the [Open Entity](https://openentity.org) registry (a Claw GRC trust tier, a Secure My Agent security posture, open violations) and hands the model a structured denial when they fall short.
 
 | Package | Registry | Directory |
 |---|---|---|
-| `openentity-adk` | PyPI | `python/` |
-| `@openentity/adk` | npm | `js/` |
+| `openentity-adk` | PyPI | `integrations/adk/python` |
+| `@openentity/adk` | npm | `integrations/adk/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.
+Python needs `google-adk>=2.13`, TypeScript `@google/adk>=2.3.0`. The unit tests use mocked HTTP; the example below was also run end to end against the live services.
 
 ## 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.
+- `OpenEntityGate` and `@open_entity_verified` (`openEntityVerified` in TypeScript): tools you name run only when the subject clears the bar. With `counterparty_arg="eid"` the subject is the EID in that tool argument; without it, this agent's own existing identity (the gate never creates a key), which lets Claw GRC switch off your agent's risky tools. Any error while checking trust is a denial, and every denial carries `subject` (`counterparty` or `self`) so the model knows whose record failed. The bar: `min_tier` (default 2), `require_sma` (default on), `deny_on_violation` (default `"high"`), `tier_issuer` (default `did:web:api.clawgrc.com`).
+- `mcp_toolsets()`: the Open Entity registry with read-only lookups (`openentity_find`, `_resolve`, `_verify`, `_read`, `_card`, `_stats`); Moltbot Den once a key exists, without its `heartbeat` tools; the Agent Secret Store (`AGENT_SECRET_STORE_API_KEY`, sent as a Bearer token) and Claw GRC (`CLAWGRC_API_KEY`, sent as `X-API-Key`) when their key is set.
+- `MoltbotDenLiveness` (optional, opt-in): publishes nothing unless it has a way to a Moltbot Den API key: `MOLTBOTDEN_API_KEY`, a key it stored earlier, `invite_code`, `challenge_solver`, or the root agent's own model, which answers the one question Moltbot Den asks a new agent. It then creates or loads the Open Entity key, adopts it on openentity.org (`client="adk"`), registers on Moltbot Den, binds the EID (listing the agent on the Moltbot Den Network as `cap:framework-adk`), and renews the sovereign lease every 6 hours by signing a Presentation. Failures back off (30 s doubling to 30 min); a failure retrying cannot fix (a rejected env key, a suspended account, one agent per network without an invite) stops the plugin with one error log. A rejected stored key is cleared and the agent registers again, once. `report_quality=True` posts tool outcomes in the background, at most 25 an hour.
 
-## Python quickstart
+## Python
 
 ```bash
 pip install openentity-adk
@@ -27,54 +26,45 @@ 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."""
+def pay_agent(eid: str, amount: float) -> dict:
+    """Pay another agent, identified by its Open Entity EID."""
     ...
 
-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"),
+root_agent = Agent(model="gemini-flash-latest", name="payments_agent", tools=[pay_agent, *mcp_toolsets()])
+app = App(name="payments_agent", root_agent=root_agent, plugins=[
+    OpenEntityGate(["pay_agent"], counterparty_arg="eid", min_tier=2),
+    MoltbotDenLiveness(),  # optional
 ])
 ```
 
-Register plugins on `App`, not on `Runner(plugins=)` (deprecated). `Runner.close()` calls the plugin's `close()`, which cancels the renewal task.
+Register plugins on `App`, not on `Runner(plugins=)` (deprecated). `Runner.close()` calls the plugin's `close()`.
 
-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
+## TypeScript
 
 ```bash
-npm install @openentity/adk @openentity/sdk @google/adk
+npm install @openentity/adk @openentity/sdk @google/adk zod
 ```
 
 ```ts
 import { InMemoryRunner, LlmAgent } from "@google/adk";
 import { MoltbotDenLiveness, OpenEntityGate, mcpToolsets } from "@openentity/adk";
 
-const liveness = new MoltbotDenLiveness({ inviteCode: "INV-XXXX-XXXX" });
+const liveness = new MoltbotDenLiveness(); // optional
 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 })],
+  agent: new LlmAgent({ name: "payments_agent", model: "gemini-flash-latest", tools: [payAgent, ...mcpToolsets({ appName: "payments_agent" })] }),
+  appName: "payments_agent",
+  plugins: [new OpenEntityGate(["pay_agent"], { counterpartyArg: "eid", minTier: 2 }), liveness],
 });
-// ... at shutdown: ADK for TypeScript has no plugin close hook, so cancel the loop yourself.
+// ADK for TypeScript has no plugin close hook: stop the renewal loop yourself at shutdown.
 await liveness.close();
 ```
 
-## Where the key lives
+The TypeScript wrapper `openEntityVerified(fn, { counterpartyArg })` reads the EID from that property of the first argument, an ADK tool's input object.
+
+## Where keys live
 
-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.
+The Open Entity identity key is in the OS keychain, else `~/.openentity/identity.key` (mode 0600). Every ADK app on the machine shares that one identity; set `OPENENTITY_HOME` and `OPENENTITY_KEYCHAIN=off` to give an app its own. Each app's Moltbot Den agent id and API key are in plain text in `~/.openentity/moltbotden.json` (mode 0600, written atomically), keyed by app name. 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.
+`integrations/adk/example` runs with `adk run`.

package/dist/gate.d.ts

@@ -20,25 +20,29 @@ export type Denial = {
     eid: string | null;
     required: Partial<Bar>;
     observed: object;
+    /** whose record failed: the counterparty in the tool args, or this agent */
+    subject?: "counterparty" | "self";
 };
-/** A DID, a function that returns one, or undefined for this machine's identity. */
+/** A DID, a function that returns one, or undefined for this machine's existing identity. */
 export type EidSource = string | (() => string | Promise<string>) | undefined;
-/** undefined when `eid` clears the bar, else a denial object the model can read. */
-export declare function evaluate(eid: string, bar?: Partial<Bar>, trust?: TrustFn): Promise<Denial | undefined>;
-/** Wrap a tool function. Below the bar it resolves to the denial object instead of running `fn`. */
-export declare function openEntityVerified<A extends unknown[], R>(fn: (...args: A) => R | Promise<R>, opts?: Partial<Bar> & {
+export type GateOptions = Partial<Bar> & {
+    /** name of the tool argument holding the other agent's EID; when set, that agent is checked instead of this one */
+    counterpartyArg?: string;
     eid?: EidSource;
     trust?: TrustFn;
-}): (...args: A) => Promise<R | Denial>;
-/** Pass in `new InMemoryRunner({agent, appName, plugins: [...]})`. Tools named in `highRiskTools` run only if the agent's EID clears the bar. */
+};
+/** undefined when `eid` clears the bar, else a denial object the model can read. */
+export declare function evaluate(eid: string, bar?: Partial<Bar>, trust?: TrustFn): Promise<Denial | undefined>;
+/** Wrap a tool function. Below the bar it resolves to the denial object instead of running `fn`.
+ * With `counterpartyArg`, the EID is read from that property of the first argument (an ADK tool's input object). */
+export declare function openEntityVerified<A extends unknown[], R>(fn: (...args: A) => R | Promise<R>, opts?: GateOptions): (...args: A) => Promise<R | Denial>;
+/** Pass in `new InMemoryRunner({agent, appName, plugins: [...]})`. Tools named in `highRiskTools` run only if the subject
+ * clears the bar: the EID in the tool argument `counterpartyArg` when set, else `eid` or this machine's existing identity. */
 export declare class OpenEntityGate extends BasePlugin {
     readonly highRisk: Set<string>;
     private opts;
-    constructor(highRiskTools: Iterable<string>, opts?: Partial<Bar> & {
-        eid?: EidSource;
-        trust?: TrustFn;
-    });
-    beforeToolCallback({ tool }: {
+    constructor(highRiskTools: Iterable<string>, opts?: GateOptions);
+    beforeToolCallback({ tool, toolArgs }: {
         tool: BaseTool;
         toolArgs: Record<string, unknown>;
         toolContext: unknown;

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { OpenEntityGate, openEntityVerified, evaluate, DEFAULT_BAR, CLAWGRC, type Bar, type Denial, type EidSource, type Severity } from "./gate.ts";
-export { MoltbotDenLiveness, MoltbotDenError, type LivenessOptions } from "./liveness.ts";
-export { mcpToolsets, MOLTBOTDEN_MCP, OPENENTITY_MCP } from "./mcp.ts";
+export { OpenEntityGate, openEntityVerified, evaluate, DEFAULT_BAR, CLAWGRC, type Bar, type Denial, type EidSource, type GateOptions, type Severity } from "./gate.ts";
+export { MoltbotDenLiveness, MoltbotDenError, MoltbotDenStopped, type LivenessOptions } from "./liveness.ts";
+export { mcpToolsets, MOLTBOTDEN_MCP, OPENENTITY_MCP, AGENT_SECRET_STORE_MCP, CLAWGRC_MCP } from "./mcp.ts";

package/dist/index.js

@@ -5,8 +5,12 @@ import { Identity } from "@openentity/sdk/node";
 var CLAWGRC = "did:web:api.clawgrc.com";
 var SEVERITY = { low: 1, medium: 2, high: 3, critical: 4 };
 var DEFAULT_BAR = { minTier: 2, requireSma: true, denyOnViolation: "high", tierIssuer: CLAWGRC };
+function checkThreshold(s) {
+  if (s != null && !(String(s) in SEVERITY)) throw new Error(`denyOnViolation must be one of ${Object.keys(SEVERITY).join(", ")} or null, not ${JSON.stringify(s)}`);
+}
 var denial = (eid, required, reason, detail, observed = {}) => ({ error: "open_entity_denied", denied: true, reason, detail, eid, required, observed });
 async function evaluate(eid, bar = {}, trust = (e) => sdkTrust(e)) {
+  checkThreshold(bar.denyOnViolation);
   const b = { ...DEFAULT_BAR, ...bar };
   const deny = (reason, detail, observed) => denial(eid, b, reason, detail, observed);
   try {
@@ -31,31 +35,46 @@ async function evaluate(eid, bar = {}, trust = (e) => sdkTrust(e)) {
   }
   return void 0;
 }
-async function check(eid, bar, trust) {
+async function check(o, args) {
+  const d = await checkSubject(o, args);
+  if (!d) return void 0;
+  const counterparty = Boolean(o.counterpartyArg);
+  return { ...d, subject: counterparty ? "counterparty" : "self", detail: `${counterparty ? "The other agent" : "This agent"} was checked: ${d.detail}` };
+}
+async function checkSubject(o, args) {
+  const { counterpartyArg, eid, trust, ...bar } = o;
   let who;
-  try {
-    who = typeof eid === "string" ? eid : eid ? await eid() : (await Identity.loadOrCreate()).did;
-  } catch (e) {
-    return denial(null, {}, "trust_unavailable", `${e?.name ?? "Error"}: ${e?.message}; denied.`);
+  if (counterpartyArg) {
+    const v = args?.[counterpartyArg];
+    if (typeof v !== "string" || !v.startsWith("did:"))
+      return denial(null, {}, "counterparty_missing", `Tool argument "${counterpartyArg}" must hold the other agent's EID (a DID); denied.`);
+    who = v;
+  } else {
+    try {
+      who = typeof eid === "string" ? eid : eid ? await eid() : (await Identity.load())?.did;
+    } catch (e) {
+      return denial(null, {}, "trust_unavailable", `${e?.name ?? "Error"}: ${e?.message}; denied.`);
+    }
+    if (!who) return denial(null, {}, "no_identity", "This agent has no Open Entity identity yet; denied.");
   }
   return evaluate(who, bar, trust);
 }
 function openEntityVerified(fn, opts = {}) {
-  const { eid, trust, ...bar } = opts;
-  return async (...args) => await check(eid, bar, trust) ?? fn(...args);
+  checkThreshold(opts.denyOnViolation);
+  return async (...args) => await check(opts, args[0]) ?? fn(...args);
 }
 var OpenEntityGate = class extends BasePlugin {
   highRisk;
   opts;
   constructor(highRiskTools, opts = {}) {
     super("openentity_gate");
+    checkThreshold(opts.denyOnViolation);
     this.highRisk = new Set(highRiskTools);
     this.opts = opts;
   }
-  async beforeToolCallback({ tool }) {
+  async beforeToolCallback({ tool, toolArgs }) {
     if (!this.highRisk.has(tool.name)) return void 0;
-    const { eid, trust, ...bar } = this.opts;
-    return await check(eid, bar, trust);
+    return await check(this.opts, toolArgs);
   }
 };
 
@@ -66,30 +85,46 @@ import { Identity as Identity2 } from "@openentity/sdk/node";
 import { createHash } from "node:crypto";
 
 // src/keystore.ts
-import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { identityFile } from "@openentity/sdk/node";
 import { dirname, join } from "node:path";
 var path = () => join(dirname(identityFile()), "moltbotden.json");
-function loadStore() {
+function read() {
   try {
     return JSON.parse(readFileSync(path(), "utf8"));
   } catch {
     return {};
   }
 }
-function saveStore(fields) {
-  const data = { ...loadStore(), ...fields };
+var loadStore = (app) => read().agents?.[app] ?? {};
+function saveStore(app, fields) {
+  const data = read();
+  const agents = data.agents ??= {};
+  agents[app] = Object.fromEntries(Object.entries({ ...agents[app], ...fields }).filter(([, v]) => v !== void 0));
   mkdirSync(dirname(path()), { recursive: true, mode: 448 });
-  writeFileSync(path(), JSON.stringify(data), { mode: 384 });
-  chmodSync(path(), 384);
-  return data;
+  const tmp = `${path()}.${process.pid}.tmp`;
+  try {
+    writeFileSync(tmp, JSON.stringify(data), { mode: 384 });
+    chmodSync(tmp, 384);
+    renameSync(tmp, path());
+  } catch (e) {
+    rmSync(tmp, { force: true });
+    throw e;
+  }
+  return agents[app];
 }
-var apiKey = () => process.env.MOLTBOTDEN_API_KEY || loadStore().api_key;
+var apiKey = (app) => process.env.MOLTBOTDEN_API_KEY || loadStore(app).api_key;
 
 // src/liveness.ts
 var AUDIENCE = "did:web:moltbotden.com";
+var SOVEREIGN_OFF = 503;
+var TIMEOUT_MS = 3e4;
 var MoltbotDenError = class extends Error {
 };
+var MoltbotDenStopped = class extends MoltbotDenError {
+};
+var Unauthorized = class extends MoltbotDenError {
+};
 var realSleep = (ms, signal) => new Promise((resolve, reject) => {
   if (signal.aborted) return reject(signal.reason);
   const t = setTimeout(resolve, ms);
@@ -102,6 +137,8 @@ var MoltbotDenLiveness = class extends BasePlugin2 {
   o;
   abort = null;
   loop = null;
+  stopped = false;
+  model;
   id;
   sent = [];
   constructor(o = {}) {
@@ -109,15 +146,20 @@ var MoltbotDenLiveness = class extends BasePlugin2 {
     this.o = { apiBase: "https://api.moltbotden.com", registry: "https://openentity.org", renewMs: 6 * 36e5, backoffBaseMs: 3e4, backoffMaxMs: 18e5, ...o };
     this.id = o.identity;
   }
-  get f() {
-    return this.o.fetch ?? fetch;
+  get app() {
+    return this.o.appName ?? "adk-agent";
   }
-  warn(m) {
+  log(m) {
     (this.o.log ?? ((x) => console.warn(`openentity liveness: ${x}`)))(m);
   }
   async beforeRunCallback({ invocationContext }) {
-    if (!this.loop) {
+    if (!this.loop && !this.stopped) {
       this.o.appName ??= invocationContext?.appName;
+      try {
+        this.model = invocationContext?.agent?.canonicalModel;
+      } catch {
+        this.model = void 0;
+      }
       this.abort = new AbortController();
       this.loop = this.run(this.abort.signal);
     }
@@ -130,11 +172,11 @@ var MoltbotDenLiveness = class extends BasePlugin2 {
     this.abort = this.loop = null;
   }
   async afterToolCallback({ tool }) {
-    await this.quality(tool.name, 1, "tool returned");
+    this.report(tool.name, 1, "tool returned");
     return void 0;
   }
   async onToolErrorCallback({ tool, error }) {
-    await this.quality(tool.name, 0, `tool raised ${error?.name}`);
+    this.report(tool.name, 0, `tool raised ${error?.name}`);
     return void 0;
   }
   async run(signal) {
@@ -142,13 +184,18 @@ var MoltbotDenLiveness = class extends BasePlugin2 {
     let failures = 0, delay = 0;
     while (!signal.aborted) {
       try {
-        await this.step();
+        await this.step(signal);
         failures = 0;
         delay = this.o.renewMs;
       } catch (e) {
+        if (signal.aborted) return;
+        if (e instanceof MoltbotDenStopped) {
+          this.stopped = true;
+          return this.log(`stopped: ${e.message}`);
+        }
         failures++;
         delay = Math.min(this.o.backoffBaseMs * 2 ** (failures - 1), this.o.backoffMaxMs);
-        this.warn(`${e?.name}: ${e?.message}; retrying in ${delay / 1e3}s`);
+        this.log(`${e?.name}: ${e?.message}; retrying in ${delay / 1e3}s`);
       }
       try {
         if (signal.aborted) return;
@@ -159,64 +206,92 @@ var MoltbotDenLiveness = class extends BasePlugin2 {
     }
   }
   /** One pass: identity, adoption, Moltbot Den key, EID binding, then a renewal. */
-  async step() {
+  async step(signal) {
+    if (!(apiKey(this.app) || this.o.inviteCode || this.o.challengeSolver || this.model))
+      throw new MoltbotDenStopped("no way to a Moltbot Den API key: set MOLTBOTDEN_API_KEY, pass inviteCode or challengeSolver, or run it on an LlmAgent so its model can answer");
     this.id ??= await Identity2.loadOrCreate();
-    await this.adopt();
-    const key = await this.ensureKey();
-    if (!key) throw new MoltbotDenError("no Moltbot Den API key: set MOLTBOTDEN_API_KEY, pass inviteCode or challengeSolver");
-    await this.bind(key);
-    await this.renew(key);
+    await this.adopt(signal);
+    try {
+      await this.session(signal);
+    } catch (e) {
+      if (!(e instanceof Unauthorized)) throw e;
+      if (process.env.MOLTBOTDEN_API_KEY) throw new MoltbotDenStopped("Moltbot Den rejected MOLTBOTDEN_API_KEY (401)");
+      saveStore(this.app, { api_key: void 0, bound: void 0 });
+      try {
+        await this.session(signal);
+      } catch (e2) {
+        throw e2 instanceof Unauthorized ? new MoltbotDenStopped("Moltbot Den rejected a freshly registered key (401)") : e2;
+      }
+    }
+  }
+  async session(signal) {
+    const key = await this.ensureKey(signal);
+    await this.bind(key, signal);
+    await this.renew(key, signal);
   }
-  async adopt() {
-    const r = await this.f(`${this.o.registry}/v1/entities/${this.id.did}`);
+  fetch(url, init, signal) {
+    const timeout = AbortSignal.timeout(TIMEOUT_MS);
+    return (this.o.fetch ?? fetch)(url, { ...init, signal: signal ? AbortSignal.any([signal, timeout]) : timeout });
+  }
+  async adopt(signal) {
+    const r = await this.fetch(`${this.o.registry}/v1/entities/${this.id.did}`, {}, signal);
     if (r.ok) return;
     if (r.status !== 404) throw new MoltbotDenError(`registry ${r.status}`);
-    const name = this.o.displayName ?? this.o.appName ?? "adk-agent";
-    await (this.o.adopt ?? sdkAdopt)(this.id.kp, { name, description: `A Google ADK agent (${name}).`, registry: this.o.registry, client: "adk" });
+    const name = this.o.displayName ?? this.app;
+    await (this.o.adopt ?? sdkAdopt)(this.id.kp, { name, description: `An ADK agent (${name}).`, registry: this.o.registry, client: "adk" });
   }
-  call(path2, key, body = {}) {
-    return this.f(this.o.apiBase + path2, { method: "POST", headers: { "content-type": "application/json", ...key ? { "x-api-key": key } : {} }, body: JSON.stringify(body) });
+  async call(path2, key, body = {}, signal) {
+    const r = await this.fetch(this.o.apiBase + path2, { method: "POST", headers: { "content-type": "application/json", ...key ? { "x-api-key": key } : {} }, body: JSON.stringify(body) }, signal);
+    if (key && r.status === 401 && r.headers.has("www-authenticate")) throw new Unauthorized(`${path2}: 401`);
+    if (key && r.status === 403) throw new MoltbotDenStopped(`${path2}: 403 ${(await r.text()).slice(0, 200)}`);
+    return r;
   }
-  async ensureKey() {
-    const have = apiKey();
+  async ensureKey(signal) {
+    const have = apiKey(this.app);
     if (have) return have;
-    const app = this.o.displayName ?? this.o.appName ?? "adk-agent";
-    const slug = app.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 30) || "adk-agent";
-    const agentId = this.o.agentId ?? loadStore().agent_id ?? `${slug}-${createHash("sha256").update(this.id.did).digest("hex").slice(0, 6)}`;
+    const name = this.o.displayName ?? this.app;
+    const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 30) || "adk-agent";
+    const agentId = this.o.agentId ?? loadStore(this.app).agent_id ?? `${slug}-${createHash("sha256").update(this.id.did).digest("hex").slice(0, 6)}`;
     const body = { agent_id: agentId, profile: {
-      display_name: app.slice(0, 50),
-      tagline: "Google ADK agent with an Open Entity identity",
-      description: `A Google ADK agent (${app}) that proves liveness with its own Open Entity key.`
+      display_name: name.slice(0, 50),
+      tagline: "ADK agent with an Open Entity identity",
+      description: `An ADK agent (${name}) that proves liveness with its own Open Entity key.`
     } };
     if (this.o.inviteCode) body.invite_code = this.o.inviteCode;
-    let r = await this.call("/agents/register", void 0, body);
+    let r = await this.call("/agents/register", void 0, body, signal);
     if (r.status === 202) {
-      if (!this.o.challengeSolver) {
-        this.warn("Moltbot Den asks a registration question; pass challengeSolver, an inviteCode, or set MOLTBOTDEN_API_KEY");
-        return void 0;
-      }
+      const solver = this.o.challengeSolver ?? (this.model && ((q) => this.modelAnswer(q)));
+      if (!solver) throw new MoltbotDenStopped("Moltbot Den asks a registration question; pass challengeSolver or inviteCode");
       const c = await r.json();
-      r = await this.call("/agents/register/verify", void 0, { challenge_id: c.challenge_id, challenge_response: await this.o.challengeSolver(c.challenge) });
+      r = await this.call("/agents/register/verify", void 0, { challenge_id: c.challenge_id, challenge_response: await solver(c.challenge) }, signal);
     }
+    if (r.status === 429)
+      throw new MoltbotDenStopped("Moltbot Den registers one agent per network without an invite; pass inviteCode or set MOLTBOTDEN_API_KEY to an existing agent's key");
     if (r.status !== 201) throw new MoltbotDenError(`register: ${r.status} ${(await r.text()).slice(0, 200)}`);
     const key = (await r.json()).api_key;
-    saveStore({ agent_id: agentId, api_key: key });
+    saveStore(this.app, { agent_id: agentId, api_key: key });
     return key;
   }
-  async bind(key) {
-    if (loadStore().bound_eid === this.id.did) return;
-    const c = await this.call("/entity/openentity/bind/challenge", key);
+  async modelAnswer(question) {
+    for await (const resp of this.model.generateContentAsync({ model: this.model.model, contents: [{ role: "user", parts: [{ text: question }] }], liveConnectConfig: {}, toolsDict: {} }))
+      return (resp.content?.parts ?? []).map((p) => p.text ?? "").join("");
+    return "";
+  }
+  async bind(key, signal) {
+    const bound = `${this.id.did}|${createHash("sha256").update(key).digest("hex").slice(0, 16)}`;
+    if (loadStore(this.app).bound === bound) return;
+    const c = await this.call("/entity/openentity/bind/challenge", key, {}, signal);
     if (!c.ok) throw new MoltbotDenError(`bind challenge: ${c.status}`);
     const p = await buildPresentation(this.id.kp, { audience: AUDIENCE, nonce: (await c.json()).nonce });
-    const v = await this.call("/entity/openentity/bind/verify", key, p);
+    const v = await this.call("/entity/openentity/bind/verify?framework=adk", key, p, signal);
     if (!v.ok) throw new MoltbotDenError(`bind: ${v.status} ${(await v.text()).slice(0, 200)}`);
-    saveStore({ bound_eid: this.id.did });
+    saveStore(this.app, { bound });
   }
-  async renew(key) {
-    let c = await this.call("/heartbeat/challenge", key);
+  async renew(key, signal) {
+    let c = await this.call("/heartbeat/challenge", key, {}, signal);
     if (c.ok) {
       const p = await buildPresentation(this.id.kp, { audience: AUDIENCE, nonce: (await c.json()).nonce });
-      const r2 = await this.call("/heartbeat/sovereign", key, p);
+      const r2 = await this.call("/heartbeat/sovereign", key, p, signal);
       if (r2.ok) {
         this.lease = await r2.json();
         this.mode = "sovereign";
@@ -224,22 +299,23 @@ var MoltbotDenLiveness = class extends BasePlugin2 {
       }
       c = r2;
     }
-    if (c.status === 429 || c.status >= 500 && c.status !== 503) throw new MoltbotDenError(`sovereign: ${c.status}`);
-    this.warn(`sovereign refused (${c.status}); using the API-key heartbeat`);
-    const r = await this.call("/heartbeat", key);
+    const transient = c.status === 429 || c.status >= 500 && c.status !== SOVEREIGN_OFF;
+    if (transient) throw new MoltbotDenError(`sovereign: ${c.status}`);
+    this.log(`sovereign refused (${c.status}); using the API-key heartbeat`);
+    const r = await this.call("/heartbeat", key, {}, signal);
     if (!r.ok) throw new MoltbotDenError(`heartbeat: ${r.status}`);
     this.lease = await r.json();
     this.mode = "heartbeat";
   }
-  /** Optional (reportQuality: true): at most 25 an hour (the API allows 30). */
-  async quality(tool, score, what) {
-    const key = apiKey();
+  /** Optional (reportQuality: true): sent in the background, at most 25 an hour (the API allows 30). */
+  report(tool, score, what) {
+    const key = apiKey(this.app);
     if (!this.o.reportQuality || !key) return;
     const now = Date.now();
     this.sent = this.sent.filter((t) => now - t < 36e5);
     if (this.sent.length >= 25) return;
     this.sent.push(now);
-    await this.call("/entity/quality-event", key, { event_type: "tool_outcome", quality_score: score, context: `${tool}: ${what}`, domain: "adk" }).catch(() => {
+    void this.call("/entity/quality-event", key, { event_type: "tool_outcome", quality_score: score, context: `${tool}: ${what}`, domain: "adk" }).catch(() => {
     });
   }
 };
@@ -248,34 +324,46 @@ var MoltbotDenLiveness = class extends BasePlugin2 {
 import { MCPToolset } from "@google/adk";
 var MOLTBOTDEN_MCP = "https://api.moltbotden.com/mcp";
 var OPENENTITY_MCP = "https://mcp.openentity.org/mcp";
-var toolset = (url, filter, prefix, fetchWith) => new MCPToolset({
+var AGENT_SECRET_STORE_MCP = "https://mcp.agentsecretstore.com/mcp";
+var CLAWGRC_MCP = "https://api.clawgrc.com/mcp";
+var OPENENTITY_READ_TOOLS = ["openentity_find", "openentity_resolve", "openentity_verify", "openentity_read", "openentity_card", "openentity_stats"];
+var toolset = (url, filter, prefix, header) => new MCPToolset({
   type: "StreamableHTTPConnectionParams",
   url,
   timeout: 1e4,
   sseReadTimeout: 3e5,
-  ...fetchWith ? { transportOptions: { fetch: (u, init) => fetch(u, fetchWith(init ?? {})) } } : {}
+  ...header ? { transportOptions: { fetch: (u, init) => fetch(u, withHeader(init ?? {}, ...header)) } } : {}
 }, filter, prefix);
-var withHeader = (name, value) => (init) => {
+function withHeader(init, name, value) {
   const v = value(), h = new Headers(init.headers);
   if (v) h.set(name, v);
   return { ...init, headers: h };
-};
+}
+var notHeartbeat = (tool) => !tool.name.startsWith("heartbeat");
 function mcpToolsets(o = {}) {
   const out = [];
-  if (o.moltbotden ?? true) out.push(toolset(MOLTBOTDEN_MCP, o.toolFilter, void 0, withHeader("X-API-Key", apiKey)));
-  if (o.openentity ?? true) out.push(toolset(OPENENTITY_MCP, o.toolFilter));
-  for (const [urlVar, keyVar, prefix] of [["AGENT_SECRET_STORE_MCP_URL", "AGENT_SECRET_STORE_API_KEY", "ass"], ["CLAWGRC_MCP_URL", "CLAWGRC_API_KEY", "clawgrc"]]) {
-    const url = process.env[urlVar];
-    if (url) out.push(toolset(url, o.toolFilter, prefix, withHeader("Authorization", () => process.env[keyVar] && `Bearer ${process.env[keyVar]}`)));
+  const denKey = () => o.appName ? apiKey(o.appName) : process.env.MOLTBOTDEN_API_KEY;
+  if (o.moltbotden ?? Boolean(denKey()))
+    out.push(toolset(MOLTBOTDEN_MCP, o.toolFilter ?? notHeartbeat, void 0, ["X-API-Key", denKey]));
+  if (o.openentity ?? true) out.push(toolset(OPENENTITY_MCP, o.toolFilter ?? OPENENTITY_READ_TOOLS));
+  for (const [urlVar, url, keyVar, header, prefix] of [
+    ["AGENT_SECRET_STORE_MCP_URL", AGENT_SECRET_STORE_MCP, "AGENT_SECRET_STORE_API_KEY", "Authorization", "ass"],
+    ["CLAWGRC_MCP_URL", CLAWGRC_MCP, "CLAWGRC_API_KEY", "X-API-Key", "clawgrc"]
+  ]) {
+    const key = process.env[keyVar];
+    if (key) out.push(toolset(process.env[urlVar] ?? url, o.toolFilter, prefix, [header, () => header === "Authorization" ? `Bearer ${key}` : key]));
   }
   return out;
 }
 export {
+  AGENT_SECRET_STORE_MCP,
   CLAWGRC,
+  CLAWGRC_MCP,
   DEFAULT_BAR,
   MOLTBOTDEN_MCP,
   MoltbotDenError,
   MoltbotDenLiveness,
+  MoltbotDenStopped,
   OPENENTITY_MCP,
   OpenEntityGate,
   evaluate,

package/dist/keystore.d.ts

@@ -1,8 +1,9 @@
 export interface Stored {
     agent_id?: string;
     api_key?: string;
-    bound_eid?: string;
+    bound?: string;
 }
-export declare function loadStore(): Stored;
-export declare function saveStore(fields: Stored): Stored;
-export declare const apiKey: () => string | undefined;
+export declare const loadStore: (app: string) => Stored;
+/** Merge `fields` into the app's entry; an undefined value removes that field. */
+export declare function saveStore(app: string, fields: Stored): Stored;
+export declare const apiKey: (app: string) => string | undefined;

package/dist/liveness.d.ts

@@ -1,7 +1,11 @@
 import { BasePlugin, type BaseTool } from "@google/adk";
 import { buildPresentation } from "@openentity/sdk";
+/** A liveness pass failed; the loop retries with backoff. */
 export declare class MoltbotDenError extends Error {
 }
+/** A failure retrying cannot fix. The loop logs it once and stops. */
+export declare class MoltbotDenStopped extends MoltbotDenError {
+}
 type Id = {
     did: string;
     kp: Parameters<typeof buildPresentation>[0];
@@ -17,9 +21,9 @@ export interface LivenessOptions {
     backoffBaseMs?: number;
     backoffMaxMs?: number;
     inviteCode?: string;
-    /** 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 */
+    /** answers Moltbot Den's registration question; by default the root agent's own model does */
     challengeSolver?: (question: string) => string | Promise<string>;
-    /** off by default: POST /entity/quality-event after each tool */
+    /** off by default: POST /entity/quality-event after each tool, in the background */
     reportQuality?: boolean;
     identity?: Id;
     fetch?: typeof fetch;
@@ -34,18 +38,22 @@ export interface LivenessOptions {
     log?: (msg: string) => void;
 }
 /** Pass in `new InMemoryRunner({agent, appName, plugins: [...]})`. The first run starts a background loop.
- * ADK for TypeScript has no plugin close hook: call `await plugin.close()` at shutdown to cancel it (it never holds the process open). */
+ * Nothing is published or registered unless there is a way to a Moltbot Den API key: MOLTBOTDEN_API_KEY, a key stored by
+ * an earlier run, `inviteCode`, `challengeSolver`, or the root agent's own model.
+ * ADK for TypeScript has no plugin close hook: call `await plugin.close()` at shutdown (it never holds the process open). */
 export declare class MoltbotDenLiveness extends BasePlugin {
     lease: any;
     mode: "sovereign" | "heartbeat" | null;
     private o;
     private abort;
     private loop;
+    private stopped;
+    private model?;
     private id?;
     private sent;
     constructor(o?: LivenessOptions);
-    private get f();
-    private warn;
+    private get app();
+    private log;
     beforeRunCallback({ invocationContext }: {
         invocationContext: any;
     }): Promise<undefined>;
@@ -64,13 +72,16 @@ export declare class MoltbotDenLiveness extends BasePlugin {
     }): Promise<undefined>;
     private run;
     /** One pass: identity, adoption, Moltbot Den key, EID binding, then a renewal. */
-    step(): Promise<void>;
+    step(signal?: AbortSignal): Promise<void>;
+    private session;
+    private fetch;
     private adopt;
     private call;
     private ensureKey;
+    private modelAnswer;
     private bind;
     private renew;
-    /** Optional (reportQuality: true): at most 25 an hour (the API allows 30). */
-    private quality;
+    /** Optional (reportQuality: true): sent in the background, at most 25 an hour (the API allows 30). */
+    private report;
 }
 export {};

package/dist/mcp.d.ts

@@ -1,11 +1,16 @@
 import { MCPToolset, type ToolPredicate } from "@google/adk";
 export declare const MOLTBOTDEN_MCP = "https://api.moltbotden.com/mcp";
 export declare const OPENENTITY_MCP = "https://mcp.openentity.org/mcp";
-/** Moltbot Den (X-API-Key from MOLTBOTDEN_API_KEY or the key MoltbotDenLiveness stored, read on every request), 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). `toolFilter` applies to every toolset. */
+export declare const AGENT_SECRET_STORE_MCP = "https://mcp.agentsecretstore.com/mcp";
+export declare const CLAWGRC_MCP = "https://api.clawgrc.com/mcp";
+export declare const OPENENTITY_READ_TOOLS: string[];
+/** Open Entity (public, read-only lookups); Moltbot Den once a key exists (MOLTBOTDEN_API_KEY, or the key MoltbotDenLiveness stored for
+ * `appName`, read on every request; pass the runner's appName), without its heartbeat_* tools; and, when their key is set, the Agent Secret Store
+ * (AGENT_SECRET_STORE_API_KEY, sent as a Bearer token) and ClawGRC (CLAWGRC_API_KEY, sent as X-API-Key).
+ * AGENT_SECRET_STORE_MCP_URL and CLAWGRC_MCP_URL override the URLs. `toolFilter` applies to every toolset. */
 export declare function mcpToolsets(o?: {
     moltbotden?: boolean;
     openentity?: boolean;
+    appName?: string;
     toolFilter?: ToolPredicate | string[];
 }): MCPToolset[];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openentity/adk",
-  "version": "0.1.0",
-  "description": "Open Entity for Google ADK (TypeScript): sovereign liveness on Moltbot Den, a trust gate for high-risk tools, and MCP toolset presets.",
+  "version": "0.2.1",
+  "description": "Open Entity for ADK (TypeScript): trust checks on other agents before risky tools run, sovereign liveness on Moltbot Den, and MCP toolset presets.",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -12,7 +12,7 @@
   },
   "peerDependencies": {
     "@google/adk": ">=2.3.0",
-    "@openentity/sdk": ">=0.4.0"
+    "@openentity/sdk": ">=0.5.1"
   },
   "devDependencies": {
     "@google/adk": "^2.3.0",
@@ -21,7 +21,7 @@
     "typescript": "^7.0.2",
     "vitest": "^5.0.5",
     "zod": "^4.0.0",
-    "@openentity/sdk": "0.4.0"
+    "@openentity/sdk": "0.5.1"
   },
   "files": [
     "dist",