hexgate 0.2.3__tar.gz → 0.2.5__tar.gz

{hexgate-0.2.3/hexgate.egg-info → hexgate-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexgate
-Version: 0.2.3
+Version: 0.2.5
 Summary: Hexgate — authorization infrastructure for AI agents (agent runtime + cloud client).
 License-Expression: MIT
 Requires-Python: >=3.13
@@ -34,6 +34,7 @@ Requires-Dist: ipykernel; extra == "dev"
 Requires-Dist: jupyter; extra == "dev"
 Requires-Dist: pytest>=8.4.1; extra == "dev"
 Requires-Dist: pytest-asyncio>=1.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
 Requires-Dist: ruff>=0.12.2; extra == "dev"
 Dynamic: license-file
 
@@ -50,6 +51,7 @@ Policy enforcement, signed policy bundles, per-request user scope, audit trail
 
 [![PyPI](https://img.shields.io/pypi/v/hexgate?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/hexgate/)
 [![CI](https://github.com/HexamindOrganisation/hexgate/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/HexamindOrganisation/hexgate/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/gh/HexamindOrganisation/hexgate/branch/main/graph/badge.svg?flag=sdk)](https://codecov.io/gh/HexamindOrganisation/hexgate)
 [![Downloads](https://img.shields.io/pypi/dm/hexgate?color=blueviolet)](https://pypi.org/project/hexgate/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
@@ -223,6 +225,31 @@ make dashboard-install      # pnpm install inside platform/dashboard/
 
 Then open http://localhost:5173/playground — type a message, watch the live stream of tool calls and policy decisions from your local agent.
 
+### Control-plane database (SQLite / Postgres)
+
+`make platform-api` uses a local **SQLite** file — zero setup, fine for
+dev and the test suite. Set `DATABASE_URL` to run on **Postgres** instead
+(what deployments use); bare `postgres://` URLs are normalized to the
+`asyncpg` driver. A local Postgres is in the dev compose:
+
+```bash
+make platform-api-pg      # starts Postgres (Docker) + runs the API against it
+# equivalent to:
+make postgres-up          # start Postgres, wait until healthy
+DATABASE_URL=postgresql+asyncpg://hexgate:hexgate-dev-password@localhost:5433/hexgate make platform-api
+make postgres-reset       # wipe ONLY the Postgres data volume
+```
+
+No migration system: the schema is created with `create_all`, so a model
+change means resetting the volume (`make postgres-reset`), not migrating —
+data is treated as disposable. A managed Postgres (e.g. Scaleway) needs SSL
+in the DSN, e.g. `…/hexgate?ssl=require`.
+
+`DATABASE_URL` is read from the real environment or `platform/api/.env`
+(see `.env.sample`). The opt-in `tests/test_postgres_smoke.py` is the only
+test that exercises the Postgres path (the rest run on SQLite); it runs
+when `DATABASE_URL` points at Postgres.
+
 ### Audit log (ClickHouse)
 
 Policy decisions are written to a local ClickHouse instance for the audit dashboard. Requires Docker.

hexgate-0.2.3/PKG-INFO → hexgate-0.2.5/README.md

@@ -1,42 +1,3 @@
-Metadata-Version: 2.4
-Name: hexgate
-Version: 0.2.3
-Summary: Hexgate — authorization infrastructure for AI agents (agent runtime + cloud client).
-License-Expression: MIT
-Requires-Python: >=3.13
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: bashlex>=0.18
-Requires-Dist: biscuit-python>=0.4
-Requires-Dist: cryptography>=42
-Requires-Dist: httpx>=0.28.1
-Requires-Dist: langchain
-Requires-Dist: langchain-openai
-Requires-Dist: langchain-core
-Requires-Dist: langfuse
-Requires-Dist: pydantic>=2.12.4
-Requires-Dist: python-dotenv>=1.1.1
-Requires-Dist: pyyaml>=6.0.2
-Requires-Dist: rich>=13.9.4
-Requires-Dist: websockets>=13.0
-Requires-Dist: openai-agents>=0.0.10
-Requires-Dist: langgraph>=0.2
-Requires-Dist: nest_asyncio>=1.6
-Requires-Dist: openinference-instrumentation-openai-agents>=0.1
-Requires-Dist: google-adk>=1.0
-Requires-Dist: google-genai>=1.0
-Requires-Dist: litellm>=1.50
-Requires-Dist: openinference-instrumentation-google-adk>=0.1.11
-Requires-Dist: pydantic-ai-slim>=1.88.0
-Requires-Dist: wasmtime>=20.0
-Provides-Extra: dev
-Requires-Dist: ipykernel; extra == "dev"
-Requires-Dist: jupyter; extra == "dev"
-Requires-Dist: pytest>=8.4.1; extra == "dev"
-Requires-Dist: pytest-asyncio>=1.0.0; extra == "dev"
-Requires-Dist: ruff>=0.12.2; extra == "dev"
-Dynamic: license-file
-
 <div align="center">
 
 <img src="./icon.svg" alt="Hexgate" width="96" height="96" />
@@ -50,6 +11,7 @@ Policy enforcement, signed policy bundles, per-request user scope, audit trail
 
 [![PyPI](https://img.shields.io/pypi/v/hexgate?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/hexgate/)
 [![CI](https://github.com/HexamindOrganisation/hexgate/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/HexamindOrganisation/hexgate/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/gh/HexamindOrganisation/hexgate/branch/main/graph/badge.svg?flag=sdk)](https://codecov.io/gh/HexamindOrganisation/hexgate)
 [![Downloads](https://img.shields.io/pypi/dm/hexgate?color=blueviolet)](https://pypi.org/project/hexgate/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
@@ -223,6 +185,31 @@ make dashboard-install      # pnpm install inside platform/dashboard/
 
 Then open http://localhost:5173/playground — type a message, watch the live stream of tool calls and policy decisions from your local agent.
 
+### Control-plane database (SQLite / Postgres)
+
+`make platform-api` uses a local **SQLite** file — zero setup, fine for
+dev and the test suite. Set `DATABASE_URL` to run on **Postgres** instead
+(what deployments use); bare `postgres://` URLs are normalized to the
+`asyncpg` driver. A local Postgres is in the dev compose:
+
+```bash
+make platform-api-pg      # starts Postgres (Docker) + runs the API against it
+# equivalent to:
+make postgres-up          # start Postgres, wait until healthy
+DATABASE_URL=postgresql+asyncpg://hexgate:hexgate-dev-password@localhost:5433/hexgate make platform-api
+make postgres-reset       # wipe ONLY the Postgres data volume
+```
+
+No migration system: the schema is created with `create_all`, so a model
+change means resetting the volume (`make postgres-reset`), not migrating —
+data is treated as disposable. A managed Postgres (e.g. Scaleway) needs SSL
+in the DSN, e.g. `…/hexgate?ssl=require`.
+
+`DATABASE_URL` is read from the real environment or `platform/api/.env`
+(see `.env.sample`). The opt-in `tests/test_postgres_smoke.py` is the only
+test that exercises the Postgres path (the rest run on SQLite); it runs
+when `DATABASE_URL` points at Postgres.
+
 ### Audit log (ClickHouse)
 
 Policy decisions are written to a local ClickHouse instance for the audit dashboard. Requires Docker.

{hexgate-0.2.3 → hexgate-0.2.5}/hexgate/adapters/langchain/agent.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, AsyncIterator, Iterator
+from typing import TYPE_CHECKING, Any, AsyncIterator, Iterator, Literal
 
 from langchain_core.runnables import RunnableConfig
 from langfuse import get_client, propagate_attributes
@@ -134,10 +134,10 @@ class HexgateLangchainAgent:
     async def astream_events(
         self,
         input: dict[str, Any],
-        version: str,
         *,
         user: User,
         config: RunnableConfig | None = None,
+        version: Literal["v1", "v2"] = "v2",
         **kwargs: Any,
     ) -> AsyncIterator[dict[str, Any]]:
         """Stream the agent events asynchronously inside a User scope."""
@@ -145,7 +145,10 @@ class HexgateLangchainAgent:
         async with user:
             with propagate_attributes(**self._propagate_kwargs(user, "astream_events")):
                 async for event in self._agent.astream_events(
-                    input, version, config=self._with_callbacks(config), **kwargs
+                    input,
+                    config=self._with_callbacks(config),
+                    version=version,
+                    **kwargs,
                 ):
                     yield event
 

{hexgate-0.2.3 → hexgate-0.2.5}/hexgate/agents/factory.py

@@ -190,6 +190,13 @@ def extract_input_text(input: AgentInput) -> str:
     return _extract_query_from_messages(input)
 
 
+# One-shot dedupe for the "local agent with active User scope" warning
+# inside `_resolve_user_facts`. The dashboard playground hits this once
+# per turn (and the platform-served sessions never hit it at all), so
+# without a flag the warning floods the log on every chat message.
+_warned_local_agent_user_scope: bool = False
+
+
 def _resolve_user_facts(agent: HexgateAgent) -> dict[str, list[str | int]] | None:
     """Lazily attenuate when a :class:`User` scope is active.
 
@@ -206,14 +213,22 @@ def _resolve_user_facts(agent: HexgateAgent) -> dict[str, list[str | int]] | Non
     client = agent.hexgate_client
     if client is None:
         # Local agent or test stub — User scope is set but there's nothing to
-        # attenuate against. Surface a single warning so devs see why their
-        # `requires_user` predicate isn't firing on a local-loaded agent.
-        import logging
-
-        logging.getLogger(__name__).warning(
-            "User scope active but agent has no hexgate_client; "
-            "biscuit_facts will be empty (use load_hexgate_agent for attenuation)"
-        )
+        # attenuate against. Surface a *single* warning so devs see why their
+        # `requires_user` predicate isn't firing on a local-loaded agent, then
+        # stay quiet: every subsequent turn would re-fire the same message
+        # otherwise (3-5x per chat session in the dashboard playground was
+        # the symptom).
+        global _warned_local_agent_user_scope
+        if not _warned_local_agent_user_scope:
+            import logging
+
+            logging.getLogger(__name__).warning(
+                "User scope active but agent has no hexgate_client; "
+                "biscuit_facts will be empty (use load_hexgate_agent for "
+                "attenuation). Subsequent occurrences in this process are "
+                "suppressed."
+            )
+            _warned_local_agent_user_scope = True
         return None
     from hexgate.cloud.attenuate import attenuate_for_user
     from hexgate.cloud.biscuit import (

{hexgate-0.2.3 → hexgate-0.2.5}/hexgate/audit.py

@@ -149,7 +149,13 @@ class AuditSender:
         # latch onto the first loop that drives them and reject any other
         # (e.g. a second asyncio.run()). Build them eagerly so configure()
         # stays sync, but track the loop and rebuild if it rotates.
-        self._loop: asyncio.AbstractEventLoop | None = None
+        #
+        # Capture the build-time loop so emit() can reach it from an executor
+        # thread (a sync tool under run_in_executor has no loop of its own).
+        try:
+            self._loop: asyncio.AbstractEventLoop | None = asyncio.get_running_loop()
+        except RuntimeError:
+            self._loop = None
         self._semaphore = asyncio.Semaphore(max_in_flight)
         self._client: httpx.AsyncClient | None = self._new_client()
         self._tasks: set[asyncio.Task[None]] = set()
@@ -182,11 +188,31 @@ class AuditSender:
         try:
             loop = asyncio.get_running_loop()
         except RuntimeError:
-            if not self._warned_no_loop:
-                _log.warning("audit emit called without a running event loop; skipping")
-                self._warned_no_loop = True
+            # Called off-loop (sync tool on a run_in_executor thread): route
+            # to the build-time loop instead of dropping the event.
+            loop = self._loop
+            if loop is None or loop.is_closed():
+                if not self._warned_no_loop:
+                    _log.warning(
+                        "audit emit called with no running loop and no live "
+                        "bound loop; skipping"
+                    )
+                    self._warned_no_loop = True
+                return
+            try:
+                loop.call_soon_threadsafe(self._spawn_send, event)
+            except RuntimeError:
+                pass  # loop torn down between the is_closed() check and the call
             return
         self._ensure_loop_state(loop)
+        self._spawn_send(event)
+
+    def _spawn_send(self, event: AuditEvent) -> None:
+        """Create the send task. MUST run on the bound loop's thread —
+        ``create_task`` and the loop-bound semaphore require the running loop.
+        Reached on-loop from :meth:`emit`, or via ``call_soon_threadsafe``."""
+        if self._closing or self._client is None:
+            return
         if self._semaphore.locked():
             self._dropped += 1
             if self._dropped % 100 == 1:

{hexgate-0.2.3 → hexgate-0.2.5}/hexgate/cli/_common.py

@@ -209,13 +209,11 @@ def build_runtime_from_local_agent(
     """
     import os
 
-    import yaml
-
     from hexgate.agents.factory import enforce_policy
     from hexgate.cli.register.manifest import create_manifest
     from hexgate.cli.register.register import post_manifest
     from hexgate.cloud.client import HexgateClient, HexgateConfig
-    from hexgate.security.policy_set import load_policy_set_from_dict
+    from hexgate.security.binding import platform_policy_from_payload
     from hexgate.tracing.langfuse import get_langfuse_handler
 
     manifest = create_manifest(agent_obj, description=description)
@@ -239,7 +237,7 @@ def build_runtime_from_local_agent(
 
     config = HexgateConfig.from_env()
     client = HexgateClient(config)
-    payload, _etag = client.get_agent(agent_name)
+    payload, initial_etag = client.get_agent(agent_name)
     if payload is None:
         # Invariant: no If-None-Match was sent, so a 304 is impossible.
         # Raise so `python -O` can't strip the check.
@@ -248,10 +246,22 @@ def build_runtime_from_local_agent(
             "on initial fetch (no If-None-Match was sent)"
         )
 
-    policy_payload = yaml.safe_load(payload["policy_yaml"]) or {}
-    policy = load_policy_set_from_dict(policy_payload)
+    # platform_policy_from_payload returns the canonical (engine, source)
+    # pair: handles signed-bundle vs pydantic fallback, and seeds the
+    # PlatformPolicySource with the bundle + ETag so the next refresh is
+    # a 304 unless policy changed. Without the source kwarg, refresh_policy()
+    # at the top of every stream_agent() is a no-op and dashboard edits
+    # only land at the next `hexgate serve` restart.
+    policy, refresh_source = platform_policy_from_payload(
+        client, agent_name, payload, initial_etag
+    )
 
-    enforced = enforce_policy(agent_obj, policy, approval_handler=approval_handler)
+    enforced = enforce_policy(
+        agent_obj,
+        policy,
+        approval_handler=approval_handler,
+        source=refresh_source,
+    )
 
     # Fresh handler for the streaming layer. The user's create_agent() call
     # built its own handler but discarded it; we make a new one bound to

{hexgate-0.2.3 → hexgate-0.2.5}/hexgate/cli/register/hexgate.py

@@ -28,7 +28,7 @@ def create_hexgate_manifest(
     return AgentManifest(
         name=agent.name,
         description=description,
-        framework=AgentFramework.FORTIFY,
+        framework=AgentFramework.HEXGATE,
         model=_extract_model(agent.model),
         system_prompt=_extract_system_prompt(agent.system_prompt),
         tools=[_to_tool_definition(t) for t in agent.tools],

{hexgate-0.2.3 → hexgate-0.2.5}/hexgate/cli/register/models.py

@@ -32,7 +32,7 @@ else:
 class AgentFramework(StrEnum):
     """Enum for the framework of an agent."""
 
-    FORTIFY = "hexgate"
+    HEXGATE = "hexgate"
     PYDANTIC_AI = "pydantic-ai"
     LANGCHAIN = "langchain"
     GOOGLE = "google"

{hexgate-0.2.3 → hexgate-0.2.5}/hexgate/runtime/context.py

@@ -9,7 +9,6 @@ from collections.abc import Iterator
 from contextlib import contextmanager
 from contextvars import ContextVar, Token
 from dataclasses import dataclass
-from typing import Any
 
 from pydantic import BaseModel, ConfigDict, PrivateAttr
 
@@ -96,26 +95,30 @@ class User(BaseModel):
     session_id: str | None = None
     ttl_seconds: int | None = None
 
-    # Stack so the same User instance survives nested ``async with`` blocks.
-    _tokens: list[Any] = PrivateAttr(default_factory=list)
+    # Stack of shadowed values (supports nested scopes). We save/restore via
+    # set() rather than reset(token): async-generator finalizers run __aexit__
+    # in a different Context, where a token reset would raise — set() doesn't.
+    _saved: list["User | None"] = PrivateAttr(default_factory=list)
 
     async def __aenter__(self) -> "User":
-        self._tokens.append(_CURRENT_USER.set(self))
+        self._saved.append(_CURRENT_USER.get())
+        _CURRENT_USER.set(self)
         return self
 
     async def __aexit__(self, *_: object) -> None:
-        if self._tokens:
-            _CURRENT_USER.reset(self._tokens.pop())
+        if self._saved:
+            _CURRENT_USER.set(self._saved.pop())
 
     @contextmanager
     def sync_scope(self) -> Iterator["User"]:
         """Sync mirror of ``async with self`` for sync entry points."""
-        self._tokens.append(_CURRENT_USER.set(self))
+        self._saved.append(_CURRENT_USER.get())
+        _CURRENT_USER.set(self)
         try:
             yield self
         finally:
-            if self._tokens:
-                _CURRENT_USER.reset(self._tokens.pop())
+            if self._saved:
+                _CURRENT_USER.set(self._saved.pop())
 
 
 _CURRENT_USER: ContextVar[User | None] = ContextVar(

{hexgate-0.2.3 → hexgate-0.2.5}/hexgate/security/__init__.py

@@ -74,6 +74,7 @@ from hexgate.security.rego_wasm import (
 from hexgate.security.source import (
     BundleDirPolicySource,
     PlatformPolicySource,
+    PolicyContentError,
     PolicySource,
     YamlPolicySource,
 )
@@ -107,6 +108,7 @@ __all__ = [
     "OpaNotFoundError",
     "PlatformPolicySource",
     "PolicyBundle",
+    "PolicyContentError",
     "PolicySource",
     "YamlPolicySource",
     "SignatureError",

{hexgate-0.2.3 → hexgate-0.2.5}/hexgate/security/binding.py

@@ -22,6 +22,7 @@ from hexgate.security.source import (
     _LOCAL_POLICY_ENV_VAR,
     _REQUIRE_SIGNATURE_ENV_VAR,
     PlatformPolicySource,
+    PolicyContentError,
     PolicySource,
     _local_policy_override,
     _truthy,
@@ -129,7 +130,17 @@ class PolicyBinding:
             return
         try:
             new_policy = self.source.fetch()
+        except PolicyContentError as exc:
+            # Dashboard-saved edit the runtime rejects → ERROR so the
+            # UI/runtime drift is grep-able. Still fail-soft.
+            logger.error(
+                "policy refresh for agent %r rejected platform content: %s",
+                getattr(self.enforcer, "agent_name", "?"),
+                exc,
+            )
+            return
         except Exception as exc:  # noqa: BLE001 — refresh must not crash a run
+            # Transient (network, 5xx, strict-mode signature refusal) — WARN.
             logger.warning(
                 "policy refresh for agent %r failed: %s — keeping "
                 "previously loaded policy",
@@ -170,12 +181,46 @@ def platform_policy_from_payload(
             "Refusing to fall back to the pydantic engine."
         )
     else:
+        # Loud one-shot signal (fires at load time, not per turn) so an
+        # operator running `hexgate serve` doesn't silently get the
+        # pydantic engine when they expected the production-shaped
+        # WASM path. Common cause: `opa` not installed on the platform
+        # host — see compile_bundle() in platform/api/services.py, which
+        # logs "opa not on PATH" on the server side too.
+        logger.warning(
+            "policy for %r served without a WASM bundle — falling back to "
+            "the pydantic engine. Decisions are equivalent (parity-tested), "
+            "but signature verification and signed-artifact distribution "
+            "are off. Install `opa` on the platform host and re-save the "
+            "policy to get the WASM path; set %s=true to refuse the "
+            "fallback entirely.",
+            agent_name,
+            _REQUIRE_SIGNATURE_ENV_VAR,
+        )
         policy = load_policy_set_from_dict(
             yaml.safe_load(payload.get("policy_yaml") or "") or {}
         )
 
-    # Pre-seeded so the next refresh is a 304 unless the policy changed.
+    # Pre-seeded so the next refresh is a 304 (bundle path) or a cache
+    # hit (pydantic-fallback path) unless the policy actually changed.
+    # The yaml hash is only relevant on the pydantic-fallback path —
+    # compute it from the same `policy_yaml` we just parsed above so the
+    # source's first refresh comparison matches load-time exactly.
+    import hashlib
+
+    yaml_hash: str | None = None
+    # (#3) Mirror fetch()'s guard: don't seed an ETag on the no-bundle
+    # path or the first refresh could 304 and swallow an edit.
+    seed_etag: str | None = etag
+    if bundle is None:
+        yaml_text = payload.get("policy_yaml") or ""
+        yaml_hash = hashlib.sha256(yaml_text.encode("utf-8")).hexdigest()
+        seed_etag = None
     source = PlatformPolicySource(
-        client, agent_name, initial_bundle=bundle, initial_etag=etag
+        client,
+        agent_name,
+        initial_engine=policy,
+        initial_etag=seed_etag,
+        initial_yaml_hash=yaml_hash,
     )
     return policy, source

{hexgate-0.2.3 → hexgate-0.2.5}/hexgate/security/source.py

@@ -1,12 +1,16 @@
 """Policy sources — abstractions over "where the current policy lives."
 
-The runtime fetches a :class:`PolicyBundle` (or ``None``) from a source at
-every agent run; the source decides whether that's cheap or not. Three
-implementations cover the production + local-dev workflows:
+The runtime fetches a :class:`~hexgate.security.decision.PolicyEngine`
+(or ``None``) from a source at every agent run; the source decides
+whether that's cheap or not. Three implementations cover the production
++ local-dev workflows:
 
   * :class:`PlatformPolicySource` — HTTP fetch with ``If-None-Match`` /
     ``304 Not Modified``, so unchanged bundles cost one tiny round trip
     instead of a full payload + signature verify + wasm re-instantiation.
+    Falls back to the pydantic engine (a :class:`PolicySet` derived from
+    the response's ``policy_yaml``) when the platform served no compiled
+    bundle — the typical Modal / no-opa demo deployment shape.
   * :class:`BundleDirPolicySource` — refresh a pre-built bundle directory
     on disk (today's ``HEXGATE_LOCAL_POLICY=<dir>`` path, made mtime-aware
     so a rebuild via ``hexgate policy build`` takes effect on the next run).
@@ -21,12 +25,15 @@ on the protocol, not on any concrete type.
 from __future__ import annotations
 
 import base64
+import hashlib
 import logging
 import os
 import threading
 from pathlib import Path
 from typing import TYPE_CHECKING, Protocol
 
+import yaml
+
 from hexgate.security.bundle import (
     BundleIntegrityError,
     BundleLoadError,
@@ -34,6 +41,8 @@ from hexgate.security.bundle import (
     PolicyBundle,
     build_signed_bundle,
 )
+from hexgate.security.decision import PolicyEngine
+from hexgate.security.policy_set import PolicySetError, load_policy_set_from_dict
 from hexgate.security.signing import SignatureError, decode_key
 
 if TYPE_CHECKING:
@@ -45,37 +54,58 @@ if TYPE_CHECKING:
 logger = logging.getLogger("hexgate.security.source")
 
 
+class PolicyContentError(RuntimeError):
+    """Platform served a payload, but the policy content is invalid.
+
+    Distinct from transient errors (network, signature) so
+    :meth:`PolicyBinding.refresh` can log at ``error`` level —
+    dashboard-saved-but-runtime-rejected is a correctness drift, not
+    "retry later".
+    """
+
+
 class PolicySource(Protocol):
-    """Produces a current :class:`PolicyBundle` (or ``None``) on demand.
+    """Produces a current :class:`PolicyEngine` (or ``None``) on demand.
 
     Implementations are expected to be **cheap when nothing has changed**
     — caching, ETags, or mtime checks — so the agent runtime can call
     :meth:`fetch` at the top of every run without measurable cost.
 
-    A returned ``None`` means "no bundle is configured for this source"
-    (e.g. the platform served no compiled bundle). Callers fall back to
-    whatever they had before (pydantic engine on raw YAML).
+    A returned ``None`` means "no engine is configured for this source"
+    (e.g. the platform served no policy at all). Callers keep whatever
+    engine they had before. The runtime's :class:`PolicyBinding.refresh`
+    relies on this: it only swaps when ``fetch()`` returns something
+    distinct from the current engine.
     """
 
-    def fetch(self) -> PolicyBundle | None: ...
+    def fetch(self) -> PolicyEngine | None: ...
 
 
 class PlatformPolicySource:
-    """Pull + verify a signed bundle from the platform, with ETag/304.
-
-    Holds the last seen bundle and its ``wasm_hash`` (the ETag the
-    platform serves). Each :meth:`fetch` sends ``If-None-Match`` and:
-
-      * ``304`` → returns the cached bundle without touching wasmtime or
-        the signature path.
-      * ``200`` → decodes + verifies the new payload, caches it, returns.
-      * payload with no bundle → returns ``None`` (the platform couldn't
-        compile, e.g. opa missing on the control plane — the SDK then
-        falls back to its pydantic engine).
-
-    Verification fails are fatal (a tampered platform bundle is never
-    silently downgraded). The signature is checked against the same
-    public key the SDK already trusts for biscuit verification.
+    """Pull a current policy engine from the platform, with ETag/304.
+
+    Two engines flow out, depending on what the platform has compiled:
+
+      * **WASM bundle** (production shape) — when the platform's
+        ``compiled_wasm`` is populated, we get a signed bundle back and
+        return a verified :class:`PolicyBundle`. ETag = ``wasm_hash``;
+        unchanged bundles hit ``304`` and re-use the cached object.
+      * **Pydantic fallback** (no-opa / demo shape) — when the platform
+        couldn't compile (no ``opa`` on the control plane), the response
+        carries ``policy_yaml`` but null bundle fields. We hash the yaml,
+        compare against the last seen hash, and re-construct a fresh
+        :class:`PolicySet` only when the yaml content actually changed.
+
+    Without the pydantic-fallback branch a policy edit would silently
+    no-op for any deployment without opa — :meth:`fetch` would always
+    return ``None`` (no bundle), :class:`PolicyBinding.refresh` would
+    treat that as "nothing served" and skip the swap, and the initial
+    engine built by :func:`platform_policy_from_payload` would stay
+    frozen forever.
+
+    Verification fails on the bundle path are fatal (a tampered bundle
+    is never silently downgraded). Verification uses the same public
+    key the SDK already trusts for biscuit verification.
     """
 
     def __init__(
@@ -85,46 +115,111 @@ class PlatformPolicySource:
         *,
         initial_bundle: PolicyBundle | None = None,
         initial_etag: str | None = None,
+        initial_engine: PolicyEngine | None = None,
+        initial_yaml_hash: str | None = None,
     ) -> None:
         self._client = client
         self._agent_name = agent_name
-        # Pre-seed when the caller already fetched + verified the bundle
-        # (typical at agent load time). Avoids a redundant 200 round-trip
-        # on the first refresh — that call will send If-None-Match and
-        # get a cheap 304.
-        self._cached_bundle: PolicyBundle | None = initial_bundle
+        # Pre-seed when the caller already fetched + verified at load time.
+        # `initial_engine` covers both shapes (a PolicyBundle on the WASM
+        # path, a PolicySet on the pydantic-fallback path); `initial_bundle`
+        # stays as a back-compat alias that callers used before we
+        # broadened the engine type.
+        self._cached_engine: PolicyEngine | None = (
+            initial_engine if initial_engine is not None else initial_bundle
+        )
         self._cached_etag: str | None = initial_etag
+        # Hash of the `policy_yaml` text that produced the cached *pydantic*
+        # engine. Used solely on the no-bundle branch to decide whether
+        # the platform's response represents a real change: a same-hash
+        # response returns the cached PolicySet (preserves identity → the
+        # binding's `is policy` check skips the swap); a new hash builds
+        # and caches a fresh one. ``None`` on the bundle path (we use
+        # ``_cached_etag`` for that).
+        self._cached_yaml_hash: str | None = initial_yaml_hash
         # Serialize the (read cached_etag → HTTP → write cached_*) cycle.
         # Refresh runs on a to_thread worker, so two concurrent agent runs
         # sharing one source could otherwise interleave a write to
-        # _cached_bundle with another's read of _cached_etag and pair the
+        # _cached_engine with another's read of _cached_etag and pair the
         # bundle from one response with the etag from another → a later
         # spurious 200/304. The cost is serializing refreshes for shared
         # sources, which is fine: refresh is best-effort and rare-ish per
         # turn (most calls hit a cheap 304).
         self._lock = threading.Lock()
 
-    def fetch(self) -> PolicyBundle | None:
+    def fetch(self) -> PolicyEngine | None:
         with self._lock:
             payload, etag = self._client.get_agent(
                 self._agent_name, if_none_match=self._cached_etag
             )
             # 304 — nothing changed since last fetch. Cheap path.
             if payload is None:
-                return self._cached_bundle
+                return self._cached_engine
 
             bundle = decode_and_verify_platform_bundle(
                 payload, self._client.public_key_bytes()
             )
-            self._cached_bundle = bundle
-            # Server-supplied ETag wins; fall back to wasm_hash for when the
-            # response lacked an ETag header (older platform versions).
-            self._cached_etag = etag or (
-                f'"{bundle.wasm_hash}"'
-                if bundle is not None and bundle.wasm_hash
-                else None
-            )
-            return bundle
+            if bundle is not None:
+                # WASM path. ETag tracking is on the wasm_hash; the yaml
+                # hash is irrelevant here, clear it so a later transition
+                # to the pydantic branch (platform loses opa) doesn't
+                # mistakenly reuse a stale hash from the old wasm world.
+                self._cached_engine = bundle
+                self._cached_etag = etag or (
+                    f'"{bundle.wasm_hash}"' if bundle.wasm_hash else None
+                )
+                self._cached_yaml_hash = None
+                return bundle
+
+            # No bundle — platform couldn't compile (no opa, etc.) but
+            # served the raw policy_yaml. Build a PolicySet from it.
+
+            # (#1) Refuse the downgrade under strict mode. Load-time
+            # already refuses; this catches opa-went-down mid-session.
+            # Caught by binding.refresh → keeps last verified bundle.
+            if _truthy(os.environ.get(_REQUIRE_SIGNATURE_ENV_VAR)):
+                raise RuntimeError(
+                    f"{_REQUIRE_SIGNATURE_ENV_VAR} is set but no signed "
+                    f"bundle served for {self._agent_name!r} on refresh — "
+                    "keeping last verified policy."
+                )
+
+            # (#3) Ignore server ETag on this branch — its semantics
+            # aren't defined here, and a 304 would skip the hash check
+            # below and swallow an edit. Yaml-hash is the change detector.
+            yaml_text = payload.get("policy_yaml") or ""
+            new_hash = hashlib.sha256(yaml_text.encode("utf-8")).hexdigest()
+            if new_hash == self._cached_yaml_hash and self._cached_engine is not None:
+                # Identity preserved → binding's `is` check skips the swap.
+                self._cached_etag = None
+                return self._cached_engine
+
+            # (#2) Surface parse/validate failures as PolicyContentError
+            # so binding logs at ERROR — silent swallow would recreate
+            # the original bug for invalid edits.
+            try:
+                parsed = yaml.safe_load(yaml_text) or {}
+            except yaml.YAMLError as exc:
+                raise PolicyContentError(
+                    f"unparseable policy_yaml for {self._agent_name!r}: {exc}"
+                ) from exc
+            try:
+                new_engine = load_policy_set_from_dict(parsed)
+            except (PolicySetError, ValueError, TypeError) as exc:
+                # ValueError covers pydantic ValidationError too.
+                raise PolicyContentError(
+                    f"invalid policy_yaml for {self._agent_name!r}: {exc}"
+                ) from exc
+
+            # (#4) Per-turn cost = full GET + sha256; parse only on change.
+            # Can't 304 without server ETag-on-policy_yaml (future fix).
+            # Until then the per-turn cost is one round trip + a sha256,
+            # acceptable for the demo-shaped deployments this branch
+            # targets.
+            self._cached_engine = new_engine
+            self._cached_yaml_hash = new_hash
+            self._cached_etag = None
+            return self._cached_engine
 
 
 def decode_and_verify_platform_bundle(

hexgate-0.2.3/README.md → hexgate-0.2.5/hexgate.egg-info/PKG-INFO

@@ -1,3 +1,43 @@
+Metadata-Version: 2.4
+Name: hexgate
+Version: 0.2.5
+Summary: Hexgate — authorization infrastructure for AI agents (agent runtime + cloud client).
+License-Expression: MIT
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bashlex>=0.18
+Requires-Dist: biscuit-python>=0.4
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: langchain
+Requires-Dist: langchain-openai
+Requires-Dist: langchain-core
+Requires-Dist: langfuse
+Requires-Dist: pydantic>=2.12.4
+Requires-Dist: python-dotenv>=1.1.1
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.9.4
+Requires-Dist: websockets>=13.0
+Requires-Dist: openai-agents>=0.0.10
+Requires-Dist: langgraph>=0.2
+Requires-Dist: nest_asyncio>=1.6
+Requires-Dist: openinference-instrumentation-openai-agents>=0.1
+Requires-Dist: google-adk>=1.0
+Requires-Dist: google-genai>=1.0
+Requires-Dist: litellm>=1.50
+Requires-Dist: openinference-instrumentation-google-adk>=0.1.11
+Requires-Dist: pydantic-ai-slim>=1.88.0
+Requires-Dist: wasmtime>=20.0
+Provides-Extra: dev
+Requires-Dist: ipykernel; extra == "dev"
+Requires-Dist: jupyter; extra == "dev"
+Requires-Dist: pytest>=8.4.1; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
+Requires-Dist: ruff>=0.12.2; extra == "dev"
+Dynamic: license-file
+
 <div align="center">
 
 <img src="./icon.svg" alt="Hexgate" width="96" height="96" />
@@ -11,6 +51,7 @@ Policy enforcement, signed policy bundles, per-request user scope, audit trail
 
 [![PyPI](https://img.shields.io/pypi/v/hexgate?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/hexgate/)
 [![CI](https://github.com/HexamindOrganisation/hexgate/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/HexamindOrganisation/hexgate/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/gh/HexamindOrganisation/hexgate/branch/main/graph/badge.svg?flag=sdk)](https://codecov.io/gh/HexamindOrganisation/hexgate)
 [![Downloads](https://img.shields.io/pypi/dm/hexgate?color=blueviolet)](https://pypi.org/project/hexgate/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
@@ -184,6 +225,31 @@ make dashboard-install      # pnpm install inside platform/dashboard/
 
 Then open http://localhost:5173/playground — type a message, watch the live stream of tool calls and policy decisions from your local agent.
 
+### Control-plane database (SQLite / Postgres)
+
+`make platform-api` uses a local **SQLite** file — zero setup, fine for
+dev and the test suite. Set `DATABASE_URL` to run on **Postgres** instead
+(what deployments use); bare `postgres://` URLs are normalized to the
+`asyncpg` driver. A local Postgres is in the dev compose:
+
+```bash
+make platform-api-pg      # starts Postgres (Docker) + runs the API against it
+# equivalent to:
+make postgres-up          # start Postgres, wait until healthy
+DATABASE_URL=postgresql+asyncpg://hexgate:hexgate-dev-password@localhost:5433/hexgate make platform-api
+make postgres-reset       # wipe ONLY the Postgres data volume
+```
+
+No migration system: the schema is created with `create_all`, so a model
+change means resetting the volume (`make postgres-reset`), not migrating —
+data is treated as disposable. A managed Postgres (e.g. Scaleway) needs SSL
+in the DSN, e.g. `…/hexgate?ssl=require`.
+
+`DATABASE_URL` is read from the real environment or `platform/api/.env`
+(see `.env.sample`). The opt-in `tests/test_postgres_smoke.py` is the only
+test that exercises the Postgres path (the rest run on SQLite); it runs
+when `DATABASE_URL` points at Postgres.
+
 ### Audit log (ClickHouse)
 
 Policy decisions are written to a local ClickHouse instance for the audit dashboard. Requires Docker.

{hexgate-0.2.3 → hexgate-0.2.5}/hexgate.egg-info/requires.txt

@@ -27,4 +27,5 @@ ipykernel
 jupyter
 pytest>=8.4.1
 pytest-asyncio>=1.0.0
+pytest-cov>=6.0.0
 ruff>=0.12.2

{hexgate-0.2.3 → hexgate-0.2.5}/pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta"
 # 0.2.0 (the original package name was taken on PyPI by a 2014
 # abandoned project; the team consolidated on `hexgate` for everything).
 name = "hexgate"
-version = "0.2.3"
+version = "0.2.5"
 description = "Hexgate — authorization infrastructure for AI agents (agent runtime + cloud client)."
 readme = "README.md"
 license = "MIT"
@@ -50,9 +50,35 @@ dev = [
     "jupyter",
     "pytest>=8.4.1",
     "pytest-asyncio>=1.0.0",
+    "pytest-cov>=6.0.0",
     "ruff>=0.12.2",
 ]
 
+[tool.coverage.run]
+# Branch coverage is more meaningful than line coverage — catches missed
+# else branches that line-coverage rolls over. Source listed explicitly so
+# tests/, examples/, notebooks/, and the platform/ tree don't pollute the
+# SDK's coverage number.
+branch = true
+source = ["hexgate"]
+omit = [
+    "*/__init__.py",
+    "*/builtin/*",  # packaged YAML/MD assets, not executable code
+]
+
+[tool.coverage.report]
+# Don't fail just because one printer-friendly representation is missing —
+# only meaningful when running the SDK module locally as a script.
+exclude_also = [
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "@overload",
+]
+skip_covered = false
+show_missing = true
+precision = 1
+
 [tool.setuptools.packages.find]
 include = ["hexgate*"]