agentgovern 2.2.0__tar.gz → 2.2.1__tar.gz

{agentgovern-2.2.0 → agentgovern-2.2.1}/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 2.2.1 — 2026-08-13
+
+### Fix — `register_agent()` silently no-op'd when called immediately after `init()`, the SDK's own documented call pattern (STORY-109)
+
+`register_agent()` previously scheduled its HTTP call directly against the
+background thread's event loop, gated on that loop already being confirmed
+running (`if self._loop is not None and self._loop.is_running():`). If
+called before the loop was ready — typically `<100ms` after `init()`, and
+this SDK's own README quickstart calls `register_agent()` on the very next
+line after `init()` — the registration was dropped with nothing queued
+anywhere and no error surfaced. No explicit `register_agent()` call had
+ever landed successfully in any installation of this SDK, for any agent,
+in over three months; every registered-looking agent row was actually the
+ingest route's own auto-provisioning fallback.
+
+- `register_agent()` now enqueues onto a dedicated buffer instead of
+  scheduling directly — the loop-readiness dependency is removed from the
+  call entirely. Drained by a new internal flush routine on the same
+  cadence actions already use.
+- Deduped by `external_id`: calling `register_agent()` more than once for
+  the same agent before a flush collapses to one pending entry with the
+  latest values, matching the server's own always-overwrite upsert
+  behavior, rather than queuing one call per invocation.
+- A failed registration now prints a `stderr` warning after repeated
+  consecutive failures, matching the existing warning behavior for action
+  ingest failures — never raises into the caller, but no longer silent
+  either.
+- `status()` gained two new informational fields:
+  `reg_buffer_size`, `reg_consecutive_failures`.
+- Internal null-strip added to the registration payload before
+  serialization, generalizing the same fix already applied to action
+  ingest (`_post_batch`) in `0.1.0b4` — Pydantic's `model_dump_json()`
+  sends unset optional fields as explicit JSON `null`; the server's schema
+  treats that as a distinct value from an absent key.
+
+No public API changes — `register_agent()`'s signature is unchanged, and
+every internal addition is private. Patch release: this restores
+previously-documented behavior rather than adding new capability.
+
+Full design and build record: `docs/audit-reports/story-109-register-agent-startup-race-2026-08-13.md`.
+
 ## 2.2.0 — 2026-08-11
 
 ### Fix — capture-only hook events (UserPromptSubmit/PostToolUse/Stop) no longer block on a discarded synchronous verdict; async audit-event parity (NAGT-137)

{agentgovern-2.2.0 → agentgovern-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentgovern
-Version: 2.2.0
+Version: 2.2.1
 Summary: Compliance-as-code middleware for agentic AI workflows.
 Project-URL: Homepage, https://agentgovern.zirahn.com
 Project-URL: Repository, https://github.com/ahmedkhan-zirahn/agentgovern

agentgovern-2.2.1/agentgovern/_version.py

@@ -0,0 +1 @@
+__version__ = "2.2.1"

{agentgovern-2.2.0 → agentgovern-2.2.1}/agentgovern/client.py

@@ -59,6 +59,20 @@ _BUFFER_MAXLEN = 10_000  # drop oldest when full
 _WARN_AFTER_FAILURES = 3  # consecutive failures before stderr warning
 _BACKOFF_BASE = 1.0  # initial retry delay in seconds
 _BACKOFF_MAX = 30.0  # maximum retry delay in seconds
+# STORY-109 (security review): distinct-external_id cap on self._reg_buffer,
+# on top of the dedupe register_agent() already does. Registering more than
+# this many DISTINCT agents from one process between flush ticks (every
+# ~_FLUSH_INTERVAL) is not a realistic usage pattern -- this exists to bound
+# a caller bug (e.g. register_agent() with a dynamically-generated
+# external_id in a hot loop), not to constrain legitimate use.
+_REG_BUFFER_MAXLEN = 1_000
+# Cap how many pending registrations _flush_registrations() processes per
+# call, matching the same per-tick discipline self.batch_size already
+# enforces for actions. Actions are the higher-volume path that matters more
+# to a customer; an outage plus many queued registrations must not starve
+# action ingestion behind retries for registrations that can simply wait
+# for the next tick.
+_REG_BATCH_SIZE = 100
 
 
 class AgentGovernClient:
@@ -100,7 +114,27 @@ class AgentGovernClient:
         self.flush_interval = flush_interval
 
         self._buffer: collections.deque[ActionRecord] = collections.deque(maxlen=_BUFFER_MAXLEN)
+        # STORY-109: separate from self._buffer, and keyed by external_id
+        # rather than a plain deque -- deliberately, not a second
+        # maxlen-capped deque. Two reasons:
+        #   1. A shared, bounded buffer evicts oldest-first on overflow --
+        #      since registration is appended once, before any actions
+        #      exist, it would be structurally the first thing dropped.
+        #   2. Registration is idempotent server-side (both ingest routes'
+        #      onConflictDoUpdate always overwrite with the latest values),
+        #      so a caller calling register_agent() more than once for the
+        #      same agent should collapse to one pending entry, not queue
+        #      one per call -- an OrderedDict keyed by external_id gives
+        #      that dedupe for free (re-assigning an existing key updates
+        #      its value in place, without moving its position or growing
+        #      the buffer). _REG_BUFFER_MAXLEN (security review) is a
+        #      generous cap on DISTINCT external_ids on top of that dedupe,
+        #      for the caller-bug case dedupe alone doesn't cover.
+        self._reg_buffer: collections.OrderedDict[str, AgentRegistration] = (
+            collections.OrderedDict()
+        )
         self._consecutive_failures = 0
+        self._reg_consecutive_failures = 0
         self._shutdown_event = threading.Event()
         self._loop: asyncio.AbstractEventLoop | None = None
         self._thread = threading.Thread(
@@ -165,7 +199,28 @@ class AgentGovernClient:
         tags: list[str] | None = None,
         metadata: dict[str, Any] | None = None,
     ) -> None:
-        """Fire-and-forget agent registration. Never raises."""
+        """
+        Enqueue an agent registration for async ingest. Returns immediately,
+        no I/O. Never raises.
+
+        STORY-109: previously scheduled the HTTP call directly via
+        `asyncio.run_coroutine_threadsafe`, gated on `self._loop` already
+        being set and running -- silently dropped, with nothing queued
+        anywhere, if called before the background thread's event loop was
+        confirmed ready (typically <100ms after `__init__`, and the SDK's
+        own documented quickstart calls this on the very next line after
+        `init()`, which reliably lands inside that window rather than
+        sometimes avoiding it). Enqueuing onto `self._reg_buffer` removes
+        the loop-readiness dependency from this call entirely -- the buffer
+        exists before the background thread does anything, so there is no
+        state this call needs to wait for.
+
+        Dedupes by `external_id` (security review): registering the same
+        agent twice before a flush overwrites the pending entry rather than
+        queuing a second one -- registration is idempotent server-side, so
+        only the latest values for a given agent ever need to reach the
+        server.
+        """
         try:
             payload = AgentRegistration(
                 external_id=external_id,
@@ -178,10 +233,17 @@ class AgentGovernClient:
                 tags=tags or [],
                 metadata=metadata or {},
             )
-            if self._loop is not None and self._loop.is_running():
-                asyncio.run_coroutine_threadsafe(self._post_register(payload), self._loop)
+            if external_id not in self._reg_buffer and len(self._reg_buffer) >= _REG_BUFFER_MAXLEN:
+                # Generous cap on DISTINCT external_ids, not reachable by
+                # looping the same agent (that dedupes above instead).
+                # Drop the oldest-registered distinct agent -- correctness
+                # doesn't depend on which one, since both ingest routes'
+                # upsert logic already makes final agent state
+                # order-independent.
+                self._reg_buffer.popitem(last=False)
+            self._reg_buffer[external_id] = payload
         except Exception:  # noqa: BLE001
-            pass
+            pass  # fail-open always -- payload construction errors only
 
     def heartbeat(self) -> dict[str, Any]:
         """
@@ -343,6 +405,8 @@ class AgentGovernClient:
             "policy_engine_url": self.policy_engine_url,
             "buffer_size": len(self._buffer),
             "consecutive_failures": self._consecutive_failures,
+            "reg_buffer_size": len(self._reg_buffer),
+            "reg_consecutive_failures": self._reg_consecutive_failures,
         }
 
     def shutdown(self, timeout: float = 5.0) -> None:
@@ -377,7 +441,19 @@ class AgentGovernClient:
             asyncio.run_coroutine_threadsafe(self._flush(), self._loop)
 
     async def _flush(self) -> None:
-        """Drain the buffer and POST to the ingest endpoint."""
+        """
+        Drain the registration buffer, then the action buffer, and POST to
+        the ingest endpoints.
+
+        Registrations are drained first -- not because arrival order matters
+        at the server (it doesn't: both ingest routes' upsert logic makes
+        final agent state order-independent regardless of which request
+        lands first), but so a registration and the actions that immediately
+        follow it are handled in the same tick rather than one waiting an
+        extra flush cycle behind the other.
+        """
+        await self._flush_registrations()
+
         if not self._buffer:
             return
 
@@ -434,6 +510,95 @@ class AgentGovernClient:
                     await asyncio.sleep(min(delay, _BACKOFF_MAX))
                     delay = min(delay * 2, _BACKOFF_MAX)
 
+    async def _flush_registrations(self) -> None:
+        """
+        Drain and POST up to `_REG_BATCH_SIZE` pending registrations, one at
+        a time, with the same bounded retry+backoff `_flush()` already uses
+        for actions.
+
+        STORY-109 (b): fail-open here means this never raises into the
+        caller and never blocks actions from flushing behind a stuck
+        registration -- the customer's agent is never broken by a
+        registration failure, full stop. It does NOT mean failures are
+        invisible: after `_WARN_AFTER_FAILURES` consecutive failures we
+        print to stderr, the exact observability precedent `_flush()`
+        already sets for actions below. Telling the operator something
+        failed is not a fail-open violation; silently discarding it with no
+        signal anywhere is what made this invisible for three months.
+
+        STORY-109 (security review): per-tick cap matches `self.batch_size`'s
+        own discipline for actions -- an outage plus many queued
+        registrations (each up to 3 retries with backoff) must not starve
+        action ingestion behind this call. Actions are the higher-volume
+        path that matters more to a customer; registration can wait a tick,
+        telemetry backing up is worse. Any registrations left over after
+        `_REG_BATCH_SIZE` simply wait for the next flush tick, same as an
+        oversized action buffer already does for `self._buffer`.
+        """
+        processed = 0
+        while self._reg_buffer and processed < _REG_BATCH_SIZE:
+            processed += 1
+            try:
+                _, payload = self._reg_buffer.popitem(last=False)
+            except KeyError:
+                # Defensive, not currently reachable: self._reg_buffer has
+                # exactly one producer (register_agent(), append/update
+                # only) and one consumer (this method, called serially from
+                # the background thread) -- the `while self._reg_buffer:`
+                # check can't go stale before this pop under that model.
+                # Kept anyway, matching _flush()'s own guard around the
+                # analogous self._buffer.popleft() for the same reason that
+                # guard exists there: if a future concurrency change ever
+                # adds a second consumer, "unreachable" stops being true,
+                # and removing this as dead code is exactly how that gap
+                # would get silently reintroduced. Do not remove.
+                break
+            delay = _BACKOFF_BASE
+            for attempt in range(1, 4):  # up to 3 attempts per registration
+                try:
+                    await self._post_register(payload)
+                    self._reg_consecutive_failures = 0
+                    break
+                except httpx.HTTPStatusError as exc:
+                    if exc.response.status_code == 429:
+                        # Rate limited -- drop this registration, no retry,
+                        # no failure counter increment. Same reasoning as
+                        # _flush()'s own 429 handling: retrying would
+                        # amplify load on the rate limiter.
+                        retry_after = exc.response.headers.get("Retry-After", "unknown")
+                        print(
+                            f"[agentgovern] WARNING: registration rate limit reached "
+                            f"(HTTP 429) for agent '{payload.external_id}'. Registration "
+                            f"dropped. Retry-After: {retry_after}s.",
+                            file=sys.stderr,
+                        )
+                        break
+                    self._reg_consecutive_failures += 1
+                    if self._reg_consecutive_failures >= _WARN_AFTER_FAILURES:
+                        print(
+                            f"[agentgovern] WARNING: {self._reg_consecutive_failures} "
+                            f"consecutive registration failures (HTTP "
+                            f"{exc.response.status_code}: {exc.response.text[:200]}) for "
+                            f"agent '{payload.external_id}'. Registration may be lost.",
+                            file=sys.stderr,
+                        )
+                    if attempt < 3:
+                        await asyncio.sleep(min(delay, _BACKOFF_MAX))
+                        delay = min(delay * 2, _BACKOFF_MAX)
+                except Exception as exc:  # noqa: BLE001
+                    self._reg_consecutive_failures += 1
+                    if self._reg_consecutive_failures >= _WARN_AFTER_FAILURES:
+                        print(
+                            f"[agentgovern] WARNING: {self._reg_consecutive_failures} "
+                            f"consecutive registration failures ({type(exc).__name__}: "
+                            f"{exc}) for agent '{payload.external_id}'. Registration may "
+                            "be lost. Check your API key and network connectivity.",
+                            file=sys.stderr,
+                        )
+                    if attempt < 3:
+                        await asyncio.sleep(min(delay, _BACKOFF_MAX))
+                        delay = min(delay * 2, _BACKOFF_MAX)
+
     async def _post_batch(self, batch: list[ActionRecord]) -> None:
         actions = []
         for record in batch:
@@ -477,16 +642,31 @@ class AgentGovernClient:
             resp.raise_for_status()
 
     async def _post_register(self, payload: AgentRegistration) -> None:
-        try:
-            async with httpx.AsyncClient(headers=self._auth_headers(), timeout=10.0) as client:
-                resp = await client.post(
-                    f"{self.base_url}/api/v1/ingest/agents/register",
-                    content=payload.model_dump_json(),
-                    headers={"Content-Type": "application/json"},
-                )
-                resp.raise_for_status()
-        except Exception:  # noqa: BLE001
-            pass
+        """
+        Single POST attempt -- no retry, no exception handling. Raises on
+        failure; `_flush_registrations()` owns retry/backoff/warning, the
+        same split `_post_batch()`/`_flush()` already use for actions.
+
+        Null-strips before serializing (matching `_post_batch`'s own
+        step-5 precedent, commit 30efec5, 2026-04-19): Pydantic v2's
+        `model_dump_json()` sends unset optional fields as explicit JSON
+        `null`, which the server's Zod `.optional()` fields reject as a
+        distinct value from absent-key `undefined`. The server-side fix
+        (NAGT-185, `registerSchema`'s `.nullable()`) makes this currently
+        harmless either way, but stripping here closes the gap at its
+        source rather than relying solely on the server tolerating it --
+        the exact generalization NAGT-185's own audit named and deferred.
+        """
+        d = payload.model_dump(mode="json")
+        d = {k: v for k, v in d.items() if v is not None}
+        body = json.dumps(d)
+        async with httpx.AsyncClient(headers=self._auth_headers(), timeout=10.0) as client:
+            resp = await client.post(
+                f"{self.base_url}/api/v1/ingest/agents/register",
+                content=body,
+                headers={"Content-Type": "application/json"},
+            )
+            resp.raise_for_status()
 
     def _auth_headers(self) -> dict[str, str]:
         return {

{agentgovern-2.2.0 → agentgovern-2.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentgovern"
-version = "2.2.0"
+version = "2.2.1"
 description = "Compliance-as-code middleware for agentic AI workflows."
 readme = "README.md"
 license = { text = "MIT" }