@openentity/adk 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moltbot Den
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+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.

package/README.md

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+# Open Entity for ADK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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 | `integrations/adk/python` |
+| `@openentity/adk` | npm | `integrations/adk/js` |
+
+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
+
+- `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
+
+```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 pay_agent(eid: str, amount: float) -> dict:
+    """Pay another agent, identified by its Open Entity EID."""
+    ...
+
+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()`.
+
+## TypeScript
+
+```bash
+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(); // optional
+const runner = new InMemoryRunner({
+  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],
+});
+// ADK for TypeScript has no plugin close hook: stop the renewal loop yourself at shutdown.
+await liveness.close();
+```
+
+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 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`.

package/dist/gate.d.ts

@@ -0,0 +1,51 @@
+import { BasePlugin, type BaseTool } from "@google/adk";
+import { type TrustReport } from "@openentity/sdk";
+export declare const CLAWGRC = "did:web:api.clawgrc.com";
+export type Severity = "low" | "medium" | "high" | "critical";
+export interface Bar {
+    minTier: number;
+    requireSma: boolean;
+    /** deny when a live custom:clawgrc:violation has this severity or worse; null turns the check off */
+    denyOnViolation: Severity | null;
+    /** whose trust_tier attestation counts; default did:web:api.clawgrc.com */
+    tierIssuer: string;
+}
+export declare const DEFAULT_BAR: Bar;
+type TrustFn = (eid: string) => Promise<TrustReport>;
+export type Denial = {
+    error: "open_entity_denied";
+    denied: true;
+    reason: string;
+    detail: string;
+    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 existing identity. */
+export type EidSource = string | (() => string | Promise<string>) | undefined;
+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;
+};
+/** 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?: GateOptions);
+    beforeToolCallback({ tool, toolArgs }: {
+        tool: BaseTool;
+        toolArgs: Record<string, unknown>;
+        toolContext: unknown;
+    }): Promise<Record<string, unknown> | undefined>;
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,372 @@
+// src/gate.ts
+import { BasePlugin } from "@google/adk";
+import { trust as sdkTrust } from "@openentity/sdk";
+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 {
+    const r = await trust(eid);
+    if (!r.ok) return deny("trust_unavailable", `Trust could not be established (${r.error}); denied.`);
+    if (r.withdrawn) return deny("withdrawn", "The entity withdrew its Declaration.");
+    const tier = r.trustTier[b.tierIssuer] ?? 0;
+    if (tier < b.minTier) return deny("tier_too_low", `trust_tier ${tier} from ${b.tierIssuer} is below ${b.minTier}.`, { trust_tier: tier });
+    if (b.requireSma && !r.securityPosture) return deny("sma_posture_missing", "No live Secure My Agent security_posture attestation.");
+    if (b.denyOnViolation) {
+      const bar2 = SEVERITY[b.denyOnViolation];
+      const hits = r.violations.filter((v) => (SEVERITY[v.severity] ?? bar2) >= bar2);
+      if (hits.length)
+        return deny(
+          "violation",
+          `${hits.length} live ${hits[0].issuer} violation(s) at ${b.denyOnViolation} or worse.`,
+          { violations: hits.map((v) => ({ severity: v.severity, policy: v.policy, sha256: v.sha256 })) }
+        );
+    }
+  } catch (e) {
+    return deny("trust_unavailable", `${e?.name ?? "Error"}: ${e?.message}; denied.`);
+  }
+  return void 0;
+}
+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;
+  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 = {}) {
+  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, toolArgs }) {
+    if (!this.highRisk.has(tool.name)) return void 0;
+    return await check(this.opts, toolArgs);
+  }
+};
+
+// src/liveness.ts
+import { BasePlugin as BasePlugin2 } from "@google/adk";
+import { adopt as sdkAdopt, buildPresentation } from "@openentity/sdk";
+import { Identity as Identity2 } from "@openentity/sdk/node";
+import { createHash } from "node:crypto";
+
+// src/keystore.ts
+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 read() {
+  try {
+    return JSON.parse(readFileSync(path(), "utf8"));
+  } catch {
+    return {};
+  }
+}
+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 });
+  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 = (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);
+  t.unref();
+  signal.addEventListener("abort", () => (clearTimeout(t), reject(signal.reason)), { once: true });
+});
+var MoltbotDenLiveness = class extends BasePlugin2 {
+  lease = null;
+  mode = null;
+  o;
+  abort = null;
+  loop = null;
+  stopped = false;
+  model;
+  id;
+  sent = [];
+  constructor(o = {}) {
+    super("openentity_liveness");
+    this.o = { apiBase: "https://api.moltbotden.com", registry: "https://openentity.org", renewMs: 6 * 36e5, backoffBaseMs: 3e4, backoffMaxMs: 18e5, ...o };
+    this.id = o.identity;
+  }
+  get app() {
+    return this.o.appName ?? "adk-agent";
+  }
+  log(m) {
+    (this.o.log ?? ((x) => console.warn(`openentity liveness: ${x}`)))(m);
+  }
+  async beforeRunCallback({ invocationContext }) {
+    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);
+    }
+    return void 0;
+  }
+  async close() {
+    this.abort?.abort(new Error("closed"));
+    await this.loop?.catch(() => {
+    });
+    this.abort = this.loop = null;
+  }
+  async afterToolCallback({ tool }) {
+    this.report(tool.name, 1, "tool returned");
+    return void 0;
+  }
+  async onToolErrorCallback({ tool, error }) {
+    this.report(tool.name, 0, `tool raised ${error?.name}`);
+    return void 0;
+  }
+  async run(signal) {
+    const sleep = this.o.sleep ?? realSleep;
+    let failures = 0, delay = 0;
+    while (!signal.aborted) {
+      try {
+        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.log(`${e?.name}: ${e?.message}; retrying in ${delay / 1e3}s`);
+      }
+      try {
+        if (signal.aborted) return;
+        await sleep(delay, signal);
+      } catch {
+        return;
+      }
+    }
+  }
+  /** One pass: identity, adoption, Moltbot Den key, EID binding, then a renewal. */
+  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(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);
+  }
+  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.app;
+    await (this.o.adopt ?? sdkAdopt)(this.id.kp, { name, description: `An ADK agent (${name}).`, registry: this.o.registry, client: "adk" });
+  }
+  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(signal) {
+    const have = apiKey(this.app);
+    if (have) return have;
+    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: 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, signal);
+    if (r.status === 202) {
+      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 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(this.app, { agent_id: agentId, api_key: key });
+    return 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?framework=adk", key, p, signal);
+    if (!v.ok) throw new MoltbotDenError(`bind: ${v.status} ${(await v.text()).slice(0, 200)}`);
+    saveStore(this.app, { bound });
+  }
+  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, signal);
+      if (r2.ok) {
+        this.lease = await r2.json();
+        this.mode = "sovereign";
+        return;
+      }
+      c = r2;
+    }
+    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): 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);
+    void this.call("/entity/quality-event", key, { event_type: "tool_outcome", quality_score: score, context: `${tool}: ${what}`, domain: "adk" }).catch(() => {
+    });
+  }
+};
+
+// src/mcp.ts
+import { MCPToolset } from "@google/adk";
+var MOLTBOTDEN_MCP = "https://api.moltbotden.com/mcp";
+var OPENENTITY_MCP = "https://mcp.openentity.org/mcp";
+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,
+  ...header ? { transportOptions: { fetch: (u, init) => fetch(u, withHeader(init ?? {}, ...header)) } } : {}
+}, filter, prefix);
+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 = [];
+  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,
+  mcpToolsets,
+  openEntityVerified
+};

package/dist/keystore.d.ts

@@ -0,0 +1,9 @@
+export interface Stored {
+    agent_id?: string;
+    api_key?: string;
+    bound?: string;
+}
+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

@@ -0,0 +1,87 @@
+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];
+};
+export interface LivenessOptions {
+    agentId?: string;
+    displayName?: string;
+    /** used for the display name and agent id when none is given */
+    appName?: string;
+    apiBase?: string;
+    registry?: string;
+    renewMs?: number;
+    backoffBaseMs?: number;
+    backoffMaxMs?: number;
+    inviteCode?: string;
+    /** 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, in the background */
+    reportQuality?: boolean;
+    identity?: Id;
+    fetch?: typeof fetch;
+    adopt?: (kp: Id["kp"], o: {
+        name: string;
+        description: string;
+        registry: string;
+        client: "adk";
+    }) => Promise<unknown>;
+    /** resolves after `ms`, or rejects if aborted */
+    sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+    log?: (msg: string) => void;
+}
+/** Pass in `new InMemoryRunner({agent, appName, plugins: [...]})`. The first run starts a background loop.
+ * 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 app();
+    private log;
+    beforeRunCallback({ invocationContext }: {
+        invocationContext: any;
+    }): Promise<undefined>;
+    close(): Promise<void>;
+    afterToolCallback({ tool }: {
+        tool: BaseTool;
+        toolArgs: unknown;
+        toolContext: unknown;
+        result: unknown;
+    }): Promise<undefined>;
+    onToolErrorCallback({ tool, error }: {
+        tool: BaseTool;
+        toolArgs: unknown;
+        toolContext: unknown;
+        error: Error;
+    }): Promise<undefined>;
+    private run;
+    /** One pass: identity, adoption, Moltbot Den key, EID binding, then a renewal. */
+    step(signal?: AbortSignal): Promise<void>;
+    private session;
+    private fetch;
+    private adopt;
+    private call;
+    private ensureKey;
+    private modelAnswer;
+    private bind;
+    private renew;
+    /** Optional (reportQuality: true): sent in the background, at most 25 an hour (the API allows 30). */
+    private report;
+}
+export {};

package/dist/mcp.d.ts

@@ -0,0 +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";
+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,6 +1,48 @@
 {
   "name": "@openentity/adk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "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": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@google/adk": ">=2.3.0",
+    "@openentity/sdk": ">=0.5.1"
+  },
+  "devDependencies": {
+    "@google/adk": "^2.3.0",
+    "@types/node": "^26.6.5",
+    "esbuild": "^0.28.2",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5",
+    "zod": "^4.0.0",
+    "@openentity/sdk": "0.5.1"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moltbot-den/openentity.git",
+    "directory": "integrations/adk/js"
+  },
+  "homepage": "https://openentity.org",
+  "engines": {
+    "node": ">=22.13"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --packages=external --format=esm --platform=node --target=es2022 --outfile=dist/index.js && tsc -p tsconfig.build.json",
+    "lint": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }