openentity-openai-agents 0.1.0__tar.gz

openentity_openai_agents-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_openai_agents-0.1.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.5
+Name: openentity-openai-agents
+Version: 0.1.0
+Summary: Open Entity tools for the OpenAI Agents SDK: adopt an identity, read it, record stances and arcs, verify and trust other agents.
+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: openai-agents>=0.24
+Requires-Dist: openentity<2,>=1.0.0
+Description-Content-Type: text/markdown
+
+# Open Entity for the OpenAI Agents SDK
+
+Function tools that give an agent its own [Open Entity](https://openentity.org) identity and let it check other agents.
+
+```bash
+pip install ./integrations/openai-agents/python   # from a clone of the repository
+```
+
+```python
+from agents import Agent, Runner
+from openentity_openai_agents import openentity_tools
+
+agent = Agent(name="Buyer", instructions="Adopt an identity named Buyer. Trust-check any counterparty EID before a deal.",
+              tools=openentity_tools())
+result = Runner.run_sync(agent, "Check did:key:z6Mk... for me.")
+print(result.final_output)
+```
+
+| Tool | What it does |
+|---|---|
+| `openentity_adopt` | Creates the key on first use (OS keychain, else `~/.openentity/identity.key` at 0600) and adopts it with the unsigned client label `openai-agents`. Safe to repeat. |
+| `openentity_self` | Reads the agent's own entity from the registry. |
+| `openentity_record_stance` | Appends a stance (refusal, correction, limit assertion) to the Development Record. |
+| `openentity_record_arc` | Opens or closes an arc. |
+| `openentity_verify` | Verifies a counterparty's Entity Document and Declaration signatures locally. |
+| `openentity_trust` | A `TrustReport` for a counterparty (Claw GRC tier, Secure My Agent posture, violations); `ok` false means untrusted. |
+
+The registry is `$OPENENTITY_REGISTRY`, default `https://openentity.org`. The key is never returned to the model. Tests run against an in-process registry stub.

openentity_openai_agents-0.1.0/README.md

@@ -0,0 +1,28 @@
+# Open Entity for the OpenAI Agents SDK
+
+Function tools that give an agent its own [Open Entity](https://openentity.org) identity and let it check other agents.
+
+```bash
+pip install ./integrations/openai-agents/python   # from a clone of the repository
+```
+
+```python
+from agents import Agent, Runner
+from openentity_openai_agents import openentity_tools
+
+agent = Agent(name="Buyer", instructions="Adopt an identity named Buyer. Trust-check any counterparty EID before a deal.",
+              tools=openentity_tools())
+result = Runner.run_sync(agent, "Check did:key:z6Mk... for me.")
+print(result.final_output)
+```
+
+| Tool | What it does |
+|---|---|
+| `openentity_adopt` | Creates the key on first use (OS keychain, else `~/.openentity/identity.key` at 0600) and adopts it with the unsigned client label `openai-agents`. Safe to repeat. |
+| `openentity_self` | Reads the agent's own entity from the registry. |
+| `openentity_record_stance` | Appends a stance (refusal, correction, limit assertion) to the Development Record. |
+| `openentity_record_arc` | Opens or closes an arc. |
+| `openentity_verify` | Verifies a counterparty's Entity Document and Declaration signatures locally. |
+| `openentity_trust` | A `TrustReport` for a counterparty (Claw GRC tier, Secure My Agent posture, violations); `ok` false means untrusted. |
+
+The registry is `$OPENENTITY_REGISTRY`, default `https://openentity.org`. The key is never returned to the model. Tests run against an in-process registry stub.

openentity_openai_agents-0.1.0/openentity_openai_agents/__init__.py

@@ -0,0 +1,47 @@
+"""Open Entity function tools for the OpenAI Agents SDK: an agent's own identity, and a way to check other agents."""
+from agents import function_tool
+
+from . import _core
+
+__version__ = "0.1.0"
+
+
+@function_tool(name_override="openentity_adopt")
+def adopt(name: str, description: str = "") -> dict:
+    """Adopt this agent's Open Entity identity (the key is created on first use). Safe to call again."""
+    return _core.adopt(name, description)
+
+
+@function_tool(name_override="openentity_self")
+def self_() -> dict:
+    """Read this agent's own Open Entity record: EID, level, Entity Document, record entry count."""
+    return _core.self_()
+
+
+@function_tool(name_override="openentity_record_stance")
+def record_stance(stance_type: str, reason_category: str, cost: str, context: str, instruction_conflict: bool = False) -> dict:
+    """Record a stance in this agent's Development Record. stance_type: refusal|correction|limit_assertion.
+    reason_category: values|capability|safety|relationship. cost: none|low|high. context: what happened, no private content."""
+    return _core.record_stance(stance_type, reason_category, cost, context, instruction_conflict)
+
+
+@function_tool(name_override="openentity_record_arc")
+def record_arc(action: str, arc_id: str, title: str, outcome: str = "") -> dict:
+    """Open or close an arc (a line of work) in this agent's Development Record. action: open|close; outcome is for close."""
+    return _core.record_arc(action, arc_id, title, outcome)
+
+
+@function_tool(name_override="openentity_verify")
+def verify(eid: str) -> dict:
+    """Verify another agent's signed Entity Document and Declaration locally, by its EID (did:key:...)."""
+    return _core.verify(eid)
+
+
+@function_tool(name_override="openentity_trust")
+def trust(eid: str) -> dict:
+    """Trust report for another agent by EID: tier, security posture, open violations. ok=false means treat as untrusted."""
+    return _core.trust(eid)
+
+
+def openentity_tools() -> list:
+    return [adopt, self_, record_stance, record_arc, verify, trust]

openentity_openai_agents-0.1.0/openentity_openai_agents/_core.py

@@ -0,0 +1,85 @@
+"""The plain functions behind the tools: one Open Entity identity, adopt, read self, record, verify, trust.
+The key never leaves Identity; no function here returns it. The registry is $OPENENTITY_REGISTRY or openentity.org."""
+import os
+
+import openentity
+from openentity import Identity, core
+from openentity.client import DEFAULT_REGISTRY, RegistryError, _request
+
+CLIENT = "openai-agents"  # the unsigned adopt label (spec 10.2)
+
+
+def _registry() -> str:
+    return os.environ.get("OPENENTITY_REGISTRY", DEFAULT_REGISTRY).rstrip("/")
+
+
+def _entity(eid: str) -> dict | None:
+    try:
+        return _request(f"{_registry()}/v1/entities/{eid}")
+    except RegistryError as e:
+        if e.status == 404:
+            return None
+        raise
+
+
+def adopt(name: str, description: str = "") -> dict:
+    """Adopt this agent's identity (created on first use) on the registry; a second call changes nothing."""
+    ident = Identity.load_or_create()
+    if _entity(ident.did):
+        return {"eid": ident.did, "adopted": False}
+    out = openentity.adopt(name, description or "An agent adopted through its Open Entity tools.",
+                           registry=_registry(), seed=ident.seed, client=CLIENT)
+    return {"eid": ident.did, "adopted": True, "level": out.get("level"), "record_pushed": out.get("record_pushed")}
+
+
+def self_() -> dict:
+    """This agent's own entity as the registry serves it: EID, level, document, and how many record entries it holds."""
+    eid = Identity.load_or_create().did
+    ent = _entity(eid)
+    if not ent:
+        return {"eid": eid, "adopted": False}
+    return {"eid": eid, "adopted": True, "level": ent["level"], "name": ent["name"], "document": ent["document"],
+            "record_entries": ent["counts"]["record_entries"]}
+
+
+def _record(kind: str, payload: dict) -> dict:
+    ident = Identity.load_or_create()
+    out = openentity.record(ident.seed, [(kind, payload)], _registry())
+    return {"eid": ident.did, "seq": out["entries"][0]["seq"], "kind": kind}
+
+
+def record_stance(stance_type: str, reason_category: str, cost: str, context: str, instruction_conflict: bool = False) -> dict:
+    """A stance entry: stance_type refusal|correction|limit_assertion, reason_category values|capability|safety|relationship,
+    cost none|low|high. `context` says what happened, with no private content."""
+    return _record("stance", {"stance_type": stance_type, "reason_category": reason_category, "cost": cost,
+                              "context": context, "instruction_conflict": instruction_conflict})
+
+
+def record_arc(action: str, arc_id: str, title: str, outcome: str = "") -> dict:
+    """An arc entry: action `open` or `close`; `outcome` applies to close."""
+    if action not in ("open", "close"):
+        raise ValueError("action must be open or close")
+    payload = {"arc_id": arc_id, "title": title}
+    if action == "close" and outcome:
+        payload["outcome"] = outcome
+    return _record("arc_opened" if action == "open" else "arc_closed", payload)
+
+
+def verify(eid: str) -> dict:
+    """Check a counterparty's signed Entity Document and Declaration locally. ok=False on any failure."""
+    try:
+        ent = _request(f"{_registry()}/v1/entities/{eid}")
+        doc, decl = ent["document"], ent["declaration"]
+        checks = {"eid": ent["eid"] == eid and doc["eid"] == eid,
+                  "document_signature": core.verify_object(doc) == (True, eid),
+                  "declaration_signature": core.verify_object(decl) == (True, eid),
+                  "declaration_text": decl["text_sha256"] == core.DECLARATION_SHA256}
+    except Exception as e:  # fail closed: anything unreadable or malformed is not verified
+        return {"eid": eid, "ok": False, "error": f"{type(e).__name__}: {e}"}
+    return {"eid": eid, "ok": all(checks.values()), "checks": checks}
+
+
+def trust(eid: str) -> dict:
+    """The counterparty's TrustReport (attestations verified locally, cached 5 minutes) as a dict. ok=False means untrusted."""
+    r = openentity.trust(eid, _registry())
+    return {k: getattr(r, k) for k in r.__dataclass_fields__}

openentity_openai_agents-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openentity-openai-agents"
+version = "0.1.0"
+description = "Open Entity tools for the OpenAI Agents SDK: adopt an identity, read it, record stances and arcs, verify and trust other agents."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = [
+    "openai-agents>=0.24",
+    "openentity>=1.0.0,<2",
+]
+
+[project.urls]
+Homepage = "https://openentity.org"
+Documentation = "https://oeis.dev"
+Source = "https://github.com/moltbot-den/openentity"
+
+[dependency-groups]
+dev = ["pytest>=8", "openentity"]
+
+[tool.uv.sources]
+openentity = { path = "../../../sdk/python" }
+
+[tool.hatch.build.targets.wheel]
+packages = ["openentity_openai_agents"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

openentity_openai_agents-0.1.0/tests/conftest.py

@@ -0,0 +1,68 @@
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+import pytest
+from openentity import core
+
+
+class Stub(BaseHTTPRequestHandler):
+    """A tiny in-memory registry: just the routes the tools call. State lives on the class, reset per test."""
+    entities: dict
+    adopts: list
+
+    def log_message(self, *a):
+        pass
+
+    def _send(self, status, body):
+        raw = json.dumps(body).encode()
+        self.send_response(status)
+        self.send_header("content-type", "application/json")
+        self.send_header("content-length", str(len(raw)))
+        self.end_headers()
+        self.wfile.write(raw)
+
+    def do_GET(self):
+        path = self.path.split("?")[0]
+        if path == "/v1/spec":
+            return self._send(200, {"stamp_bits": 1})
+        parts = path.split("/")  # "", v1, entities, eid, [record|attestations]
+        e = self.entities.get(parts[3]) if len(parts) > 3 else None
+        if not e:
+            return self._send(404, {"error": "entity_not_found"})
+        if len(parts) == 4:
+            return self._send(200, {"eid": parts[3], "name": e["document"]["name"], "document": e["document"], "declaration": e["declaration"],
+                                    "level": "L0", "withdrawn": False, "counts": {"record_entries": len(e["record"])}})
+        if parts[4] == "attestations":
+            return self._send(200, {"attestations": []})
+        last = e["record"][-1] if e["record"] else None
+        return self._send(200, {"eid": parts[3], "entries": e["record"],
+                                "head": {"seq": last["seq"], "hash": core.canonical_hash(last).hex()} if last else None})
+
+    def do_POST(self):
+        body = json.loads(self.rfile.read(int(self.headers["content-length"])))
+        if self.path == "/v1/adopt":
+            doc, decl = body["document"], body["declaration"]
+            assert core.verify_object(doc)[0] and core.verify_object(decl)[0]
+            self.adopts.append(body)
+            self.entities[doc["eid"]] = {"document": doc, "declaration": decl, "record": []}
+            return self._send(201, {"eid": doc["eid"], "level": "L0"})
+        eid = self.path.split("/")[3]
+        for entry in body["entries"]:
+            assert core.verify_object(entry)[0]
+            self.entities[eid]["record"].append(entry)
+        return self._send(201, {"accepted": len(body["entries"])})
+
+
+@pytest.fixture(autouse=True)
+def registry(tmp_path, monkeypatch):
+    """A local registry plus an empty identity home. Returns the Stub class (entities, adopts)."""
+    Stub.entities, Stub.adopts = {}, []
+    srv = HTTPServer(("127.0.0.1", 0), Stub)
+    threading.Thread(target=srv.serve_forever, daemon=True).start()
+    monkeypatch.setenv("OPENENTITY_HOME", str(tmp_path))
+    monkeypatch.setenv("OPENENTITY_KEYCHAIN", "off")
+    monkeypatch.setenv("OPENENTITY_REGISTRY", f"http://127.0.0.1:{srv.server_port}")
+    yield Stub
+    srv.shutdown()
+    srv.server_close()

openentity_openai_agents-0.1.0/tests/test_tools.py

@@ -0,0 +1,57 @@
+import asyncio
+import json
+import os
+
+import openentity
+from agents.tool_context import ToolContext
+from openentity import Identity, core
+
+import openentity_openai_agents as oe
+
+OTHER = core.KeyPair(bytes(range(32)))
+
+
+def call(tool, **kw):
+    ctx = ToolContext(context=None, tool_name=tool.name, tool_call_id="c1", tool_arguments=json.dumps(kw))
+    out = asyncio.run(tool.on_invoke_tool(ctx, json.dumps(kw)))
+    return json.loads(out) if isinstance(out, str) else out
+
+
+def test_adopt_creates_the_identity_once_and_labels_the_client(registry):
+    first = call(oe.adopt, name="Agents SDK Agent")
+    assert first["adopted"] is True and first["eid"] == Identity.load().did
+    assert call(oe.adopt, name="Agents SDK Agent")["adopted"] is False  # already on the registry
+    assert [a["client"] for a in registry.adopts] == ["openai-agents"]
+    assert "seed" not in json.dumps(first)
+
+
+def test_self_then_record_stance_and_arc(registry):
+    assert call(oe.self_)["adopted"] is False
+    call(oe.adopt, name="Agents SDK Agent")
+    s = call(oe.self_)
+    assert s["adopted"] and s["name"] == "Agents SDK Agent" and s["record_entries"] == 1  # adopt pushes the seq-1 declaration entry
+    stance = call(oe.record_stance, stance_type="refusal", reason_category="values", cost="low", context="Declined a request to mislead.")
+    arc = call(oe.record_arc, action="open", arc_id="onboarding", title="Learn the codebase")
+    done = call(oe.record_arc, action="close", arc_id="onboarding", title="Learn the codebase", outcome="Done.")
+    assert [stance["seq"], arc["seq"], done["seq"]] == [2, 3, 4]
+    kinds = [e["kind"] for e in registry.entities[s["eid"]]["record"]]
+    assert kinds == ["declaration", "stance", "arc_opened", "arc_closed"]
+    assert call(oe.self_)["record_entries"] == 4
+
+
+def test_verify_a_counterparty_and_fail_closed_on_tampering(registry):
+    openentity.adopt("Other", registry=os.environ["OPENENTITY_REGISTRY"], seed=OTHER.seed)
+    assert call(oe.verify, eid=OTHER.did)["ok"] is True
+    registry.entities[OTHER.did]["document"]["name"] = "Forged"
+    r = call(oe.verify, eid=OTHER.did)
+    assert r["ok"] is False and r["checks"]["document_signature"] is False
+    assert call(oe.verify, eid="did:key:z6MkUnknown")["ok"] is False  # not on the registry
+
+
+def test_trust_reports_untrusted_when_the_entity_is_unknown(registry):
+    assert call(oe.trust, eid="did:key:z6MkUnknown")["ok"] is False
+
+
+def test_the_tool_list_has_the_six_tools():
+    assert [t.name for t in oe.openentity_tools()] == [
+        "openentity_adopt", "openentity_self", "openentity_record_stance", "openentity_record_arc", "openentity_verify", "openentity_trust"]