hexgate 0.2.7__tar.gz → 0.2.9__tar.gz

hexgate-0.2.9/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: hexgate
+Version: 0.2.9
+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.14
+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
+Requires-Dist: mcp>=1.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" />
+
+# Hexgate
+
+**Runtime authorization for AI agents.**
+On every tool call, Hexgate decides whether *this user*, in *this role*, may run *this tool* with *these arguments* — allow, deny, or require approval. For OpenAI Agents, LangChain, Google ADK, Pydantic AI, or a native runtime.
+
+[**Website**](https://hexgate.ai) · [**Docs**](https://docs.hexgate.ai) · [PyPI](https://pypi.org/project/hexgate/)
+[![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)
+
+<br />
+
+<img src="./assets/hero.png" alt="Control what your agents do — not just what they say. Policy decisions streaming live from the PolicyEnforcer." />
+
+</div>
+
+---
+
+## What is Hexgate?
+
+Hexgate is two things that move together:
+
+- **`hexgate` — the SDK.** A Python runtime that gates every tool call through a typed `Decision` (allow / deny / approval-required), resolving the caller's role at call time to apply that role's rules. Wrap an existing agent without rewriting it, or build one natively — every decision is traced and audited with the caller's identity. [See supported frameworks →](https://docs.hexgate.ai/adapters/openai)
+- **The Hexgate platform** *(optional)* — a FastAPI control plane + React dashboard for editing policy in a browser, minting per-project tokens, watching live decisions stream from a serving agent, and shipping signed WASM policy bundles to production. Available as **[Hexgate Cloud](https://app.hexgate.ai)** (hosted — set one env var, no infra) or self-hosted.
+
+You can use the SDK three ways: **local** (YAML/bundle on disk, no platform), **Hexgate Cloud** (remote enforcement + audit — just set `HEXGATE_API_KEY`), or **self-hosted** (run the control plane yourself). `HEXGATE_API_URL` defaults to `https://app.hexgate.ai`, so remote enforcement is one env var away.
+
+```text
+   end user (id + role)          tool call (name + args)
+            └───────────────┬────────────────┘
+                            ▼
+              PolicyEnforcer.decide()  ◄──  policy (local YAML / bundle
+                            ▼                or signed cloud bundle)
+            allow  ·  deny  ·  approval
+                            │
+                            ▼
+      audit log — who called what, and whether it was allowed
+```
+
+## Quickstart
+
+```bash
+pip install hexgate
+```
+
+**See it enforce — no API keys.** Save a policy that gives two roles different
+limits on the *same* `refund_order` tool:
+
+<!-- Keep this refund_order policy example in sync with docs/quickstart.mdx -->
+```yaml
+# policy.yaml
+version: 1
+roles:
+  support:                                     # small USD refunds only
+    default_policy: { mode: deny }
+    tools:
+      refund_order:
+        mode: allow
+        constraints:
+          - args.amount <= 50
+          - args.currency == "USD"
+  billing:                                     # larger refunds, major currencies
+    default_policy: { mode: deny }
+    tools:
+      refund_order:
+        mode: allow
+        constraints:
+          - args.amount <= 500
+          - args.currency in ["USD", "EUR"]
+```
+
+`hexgate policy test` decides the **same $400 refund** for each role offline — no model, no keys:
+
+```bash
+hexgate policy test policy.yaml --role support \
+    --tool refund_order --args '{"amount": 400, "currency": "USD"}'
+# ✗ DENY · support → refund_order({"amount": 400, "currency": "USD"})
+#   reason: Policy on "refund_order" denied: constraint failed — args.amount <= 50
+
+hexgate policy test policy.yaml --role billing \
+    --tool refund_order --args '{"amount": 400, "currency": "USD"}'
+# ✓ ALLOW · billing → refund_order({"amount": 400, "currency": "USD"})
+```
+
+Same tool, same request — **the caller's role and the arguments decide**, enforced
+outside the model. The [full quickstart →](https://docs.hexgate.ai/quickstart) puts
+this in front of a live agent.
+
+## Documentation
+
+Full documentation lives at **[docs.hexgate.ai](https://docs.hexgate.ai)**.
+
+| | |
+|---|---|
+| [Build an agent](https://docs.hexgate.ai/guides/build-an-agent) | The two shapes — wrap an existing agent, or let the platform own the YAML. |
+| [Framework adapters](https://docs.hexgate.ai/adapters/openai) | OpenAI Agents, LangChain/LangGraph, Google ADK, Pydantic AI. |
+| [Policy](https://docs.hexgate.ai/policy/yaml-shape) | YAML shape, constraints, WASM bundles, signing, local override. |
+| [User scope + roles](https://docs.hexgate.ai/concepts/user-scope) | Per-request identity, role resolution, biscuit attenuation. |
+| [CLI](https://docs.hexgate.ai/cli/chat) | `chat`, `serve`, `register`, `policy`. |
+| [MCP servers](https://docs.hexgate.ai/concepts/mcp) | Wrap any Model Context Protocol server as policy-enforced tools. |
+| [Hexgate Cloud (hosted)](https://docs.hexgate.ai/platform/hosted) | Remote policy enforcement + audit with zero infra — get a key, set one env var. |
+| [Platform (self-hosted)](https://docs.hexgate.ai/platform/overview) | Run the control plane, dashboard, ClickHouse audit, and Resend email yourself. |
+
+## Development
+
+Contributor setup, `make` targets, and the test suites are documented in
+[Development & testing](https://docs.hexgate.ai/internals/development). The short
+version:
+
+```bash
+make install-dev     # uv sync --extra dev (first time only)
+make check           # lint + fmt-check + test (matches CI)
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+If Hexgate looks useful, [give it a ⭐ on GitHub](https://github.com/HexamindOrganisation/hexgate) — it helps more than you'd think. Built by [Hexamind](https://hexgate.ai).

hexgate-0.2.9/README.md

@@ -0,0 +1,127 @@
+<div align="center">
+
+<img src="./icon.svg" alt="Hexgate" width="96" height="96" />
+
+# Hexgate
+
+**Runtime authorization for AI agents.**
+On every tool call, Hexgate decides whether *this user*, in *this role*, may run *this tool* with *these arguments* — allow, deny, or require approval. For OpenAI Agents, LangChain, Google ADK, Pydantic AI, or a native runtime.
+
+[**Website**](https://hexgate.ai) · [**Docs**](https://docs.hexgate.ai) · [PyPI](https://pypi.org/project/hexgate/)
+[![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)
+
+<br />
+
+<img src="./assets/hero.png" alt="Control what your agents do — not just what they say. Policy decisions streaming live from the PolicyEnforcer." />
+
+</div>
+
+---
+
+## What is Hexgate?
+
+Hexgate is two things that move together:
+
+- **`hexgate` — the SDK.** A Python runtime that gates every tool call through a typed `Decision` (allow / deny / approval-required), resolving the caller's role at call time to apply that role's rules. Wrap an existing agent without rewriting it, or build one natively — every decision is traced and audited with the caller's identity. [See supported frameworks →](https://docs.hexgate.ai/adapters/openai)
+- **The Hexgate platform** *(optional)* — a FastAPI control plane + React dashboard for editing policy in a browser, minting per-project tokens, watching live decisions stream from a serving agent, and shipping signed WASM policy bundles to production. Available as **[Hexgate Cloud](https://app.hexgate.ai)** (hosted — set one env var, no infra) or self-hosted.
+
+You can use the SDK three ways: **local** (YAML/bundle on disk, no platform), **Hexgate Cloud** (remote enforcement + audit — just set `HEXGATE_API_KEY`), or **self-hosted** (run the control plane yourself). `HEXGATE_API_URL` defaults to `https://app.hexgate.ai`, so remote enforcement is one env var away.
+
+```text
+   end user (id + role)          tool call (name + args)
+            └───────────────┬────────────────┘
+                            ▼
+              PolicyEnforcer.decide()  ◄──  policy (local YAML / bundle
+                            ▼                or signed cloud bundle)
+            allow  ·  deny  ·  approval
+                            │
+                            ▼
+      audit log — who called what, and whether it was allowed
+```
+
+## Quickstart
+
+```bash
+pip install hexgate
+```
+
+**See it enforce — no API keys.** Save a policy that gives two roles different
+limits on the *same* `refund_order` tool:
+
+<!-- Keep this refund_order policy example in sync with docs/quickstart.mdx -->
+```yaml
+# policy.yaml
+version: 1
+roles:
+  support:                                     # small USD refunds only
+    default_policy: { mode: deny }
+    tools:
+      refund_order:
+        mode: allow
+        constraints:
+          - args.amount <= 50
+          - args.currency == "USD"
+  billing:                                     # larger refunds, major currencies
+    default_policy: { mode: deny }
+    tools:
+      refund_order:
+        mode: allow
+        constraints:
+          - args.amount <= 500
+          - args.currency in ["USD", "EUR"]
+```
+
+`hexgate policy test` decides the **same $400 refund** for each role offline — no model, no keys:
+
+```bash
+hexgate policy test policy.yaml --role support \
+    --tool refund_order --args '{"amount": 400, "currency": "USD"}'
+# ✗ DENY · support → refund_order({"amount": 400, "currency": "USD"})
+#   reason: Policy on "refund_order" denied: constraint failed — args.amount <= 50
+
+hexgate policy test policy.yaml --role billing \
+    --tool refund_order --args '{"amount": 400, "currency": "USD"}'
+# ✓ ALLOW · billing → refund_order({"amount": 400, "currency": "USD"})
+```
+
+Same tool, same request — **the caller's role and the arguments decide**, enforced
+outside the model. The [full quickstart →](https://docs.hexgate.ai/quickstart) puts
+this in front of a live agent.
+
+## Documentation
+
+Full documentation lives at **[docs.hexgate.ai](https://docs.hexgate.ai)**.
+
+| | |
+|---|---|
+| [Build an agent](https://docs.hexgate.ai/guides/build-an-agent) | The two shapes — wrap an existing agent, or let the platform own the YAML. |
+| [Framework adapters](https://docs.hexgate.ai/adapters/openai) | OpenAI Agents, LangChain/LangGraph, Google ADK, Pydantic AI. |
+| [Policy](https://docs.hexgate.ai/policy/yaml-shape) | YAML shape, constraints, WASM bundles, signing, local override. |
+| [User scope + roles](https://docs.hexgate.ai/concepts/user-scope) | Per-request identity, role resolution, biscuit attenuation. |
+| [CLI](https://docs.hexgate.ai/cli/chat) | `chat`, `serve`, `register`, `policy`. |
+| [MCP servers](https://docs.hexgate.ai/concepts/mcp) | Wrap any Model Context Protocol server as policy-enforced tools. |
+| [Hexgate Cloud (hosted)](https://docs.hexgate.ai/platform/hosted) | Remote policy enforcement + audit with zero infra — get a key, set one env var. |
+| [Platform (self-hosted)](https://docs.hexgate.ai/platform/overview) | Run the control plane, dashboard, ClickHouse audit, and Resend email yourself. |
+
+## Development
+
+Contributor setup, `make` targets, and the test suites are documented in
+[Development & testing](https://docs.hexgate.ai/internals/development). The short
+version:
+
+```bash
+make install-dev     # uv sync --extra dev (first time only)
+make check           # lint + fmt-check + test (matches CI)
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+If Hexgate looks useful, [give it a ⭐ on GitHub](https://github.com/HexamindOrganisation/hexgate) — it helps more than you'd think. Built by [Hexamind](https://hexgate.ai).

{hexgate-0.2.7 → hexgate-0.2.9}/hexgate/__init__.py

@@ -10,21 +10,27 @@ from hexgate.agents.factory import (
 from hexgate.agents.loader import (
     clear_registered_agents,
     list_available_agents,
-    list_builtin_agents,
     list_local_agents,
     list_registered_agents,
     load_agent,
-    load_builtin_agent,
     load_hexgate_agent,
     load_local_agent,
     load_registered_agent,
-    register_agent,
-    unregister_agent,
+    register_agent_factory,
+    unregister_agent_factory,
 )
-from hexgate.cli.register import AgentManifest, create_manifest
 from hexgate.cloud import HexgateClient, HexgateConfig
+from hexgate.manifest import AgentManifest, create_manifest
 from hexgate.runtime import LocalWorkspace, ToolUseContext, User, Workspace
-from hexgate.security import AgentPolicy
+from hexgate.security import (
+    AgentPolicy,
+    C,
+    PolicyBuilder,
+    RolePolicyBuilder,
+    assert_allows,
+    assert_denies,
+    assert_needs_approval,
+)
 from hexgate.tools import (
     agent_tool,
     bash,
@@ -32,15 +38,18 @@ from hexgate.tools import (
     glob,
     grep,
     read_file,
-    refund_order,
     write_file,
 )
-from hexgate.tools.fetch import fetch
-from hexgate.tools.websearch import web_search
 
 __all__ = [
     "AgentManifest",
     "AgentPolicy",
+    "C",
+    "PolicyBuilder",
+    "RolePolicyBuilder",
+    "assert_allows",
+    "assert_denies",
+    "assert_needs_approval",
     "HexgateClient",
     "HexgateConfig",
     "LocalWorkspace",
@@ -54,25 +63,28 @@ __all__ = [
     "create_agent",
     "create_manifest",
     "enforce_policy",
-    "fetch",
     "glob",
     "grep",
     "invoke_agent",
     "list_available_agents",
-    "list_builtin_agents",
     "list_local_agents",
     "list_registered_agents",
     "load_agent",
-    "load_builtin_agent",
     "load_hexgate_agent",
     "load_local_agent",
     "load_registered_agent",
-    "register_agent",
+    "register_agent_factory",
     "read_file",
-    "refund_order",
     "stream_agent",
     "stream_agent_raw",
-    "unregister_agent",
-    "web_search",
+    "unregister_agent_factory",
     "write_file",
 ]
+
+
+def __getattr__(name: str) -> object:
+    from hexgate.tools._relocated import RELOCATED_TOOLS, relocated_import_error
+
+    if name in RELOCATED_TOOLS:
+        raise relocated_import_error(name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{hexgate-0.2.7 → hexgate-0.2.9}/hexgate/adapters/google/runner.py

@@ -9,16 +9,20 @@ from typing import Any, AsyncGenerator, Generator
 
 import nest_asyncio
 from google.adk.agents import BaseAgent
+from google.adk.apps import App
 from google.adk.runners import Runner
 from google.adk.sessions import BaseSessionService
 from google.genai import types
 from langfuse import get_client, propagate_attributes
 from openinference.instrumentation.google_adk import GoogleADKInstrumentor
 
+from hexgate.adapters.google.usage import HexgateUsagePlugin
 from hexgate.adapters.google.wrapper import wrap_google_agent
-from hexgate.agents.factory import ApprovalHandler
+from hexgate.approvals import ApprovalHandler
+from hexgate.cloud.client import HexgateClient, HexgateConfig
 from hexgate.config.env import resolve_api_key
 from hexgate.runtime import User
+from hexgate.security.bans import resolve_ban_gate
 
 
 class HexgateRunner:
@@ -41,17 +45,26 @@ class HexgateRunner:
             )
         # Policy resolves at construction (the loud-failure point); the
         # Runner is built once — refresh swaps the enforcer's policy
-        # without touching it.
+        # without touching it. One client is shared with the ban resolver.
+        client = HexgateClient(HexgateConfig.from_env(api_key=self.api_key))
         self._wrapped_agent, self._binding = wrap_google_agent(
-            agent, api_key=self.api_key, approval_handler=approval_handler
+            agent,
+            api_key=self.api_key,
+            approval_handler=approval_handler,
+            client=client,
         )
+        plugins = list(runner_kwargs.pop("plugins", None) or [])
+        plugins.append(HexgateUsagePlugin(api_key=self.api_key))
+        app = App(name=app_name, root_agent=self._wrapped_agent, plugins=plugins)
         self._runner = Runner(
-            agent=self._wrapped_agent,
-            app_name=app_name,
+            app=app,
             session_service=session_service,
             **runner_kwargs,
         )
         self._agent_name = getattr(agent, "name", "default")
+        self._ban_gate = resolve_ban_gate(
+            self._agent_name, api_key=self.api_key, client=client
+        )
 
     def _setup_observability(self):
         """Install Langfuse + GoogleADKInstrumentor (idempotent)."""
@@ -90,6 +103,8 @@ class HexgateRunner:
         """
         self._setup_observability()
         self._binding.refresh()  # per-run policy pull; 304 when unchanged
+        if self._ban_gate is not None:
+            self._ban_gate.check(user)
         with user.sync_scope(), self._propagate(user):
             agen = self._runner.run_async(
                 user_id=user.user_id,
@@ -118,6 +133,8 @@ class HexgateRunner:
         """Run the Google ADK agent asynchronously, yielding events."""
         self._setup_observability()
         await self._binding.refresh_async()  # per-run policy pull; 304 when unchanged
+        if self._ban_gate is not None:
+            await self._ban_gate.check_async(user)
         async with user:
             with self._propagate(user):
                 async for event in self._runner.run_async(

{hexgate-0.2.7 → hexgate-0.2.9}/hexgate/adapters/google/tools.py

@@ -20,7 +20,7 @@ from google.adk.tools.function_tool import FunctionTool
 from google.adk.tools.tool_context import ToolContext
 
 from hexgate.agents.approvals import resolve_approval_async
-from hexgate.agents.factory import ApprovalHandler
+from hexgate.approvals import ApprovalHandler
 from hexgate.security.decision import DecisionOutcome
 from hexgate.security.enforcer import PolicyEnforcer
 

hexgate-0.2.9/hexgate/adapters/google/usage.py

@@ -0,0 +1,44 @@
+"""Google ADK per-call token usage capture via a ``BasePlugin``.
+
+``after_model_callback`` fires once per underlying model call, so a single
+run with several turns (tool-calling loops, sub-agent handoffs) can emit
+more than one usage event. ``callback_context.agent_name`` is read per-call
+rather than fixed at construction, since one ``Runner`` can drive several
+named sub-agents.
+"""
+
+from __future__ import annotations
+
+from google.adk.agents.callback_context import CallbackContext
+from google.adk.models.llm_response import LlmResponse
+from google.adk.plugins.base_plugin import BasePlugin
+
+from hexgate.tracing.usage import emit_llm_usage
+
+
+class HexgateUsagePlugin(BasePlugin):
+    """Emits one :class:`~hexgate.tracing.usage.LlmUsageEvent` per
+    ``after_model_callback`` callback. Never rewrites the response — always
+    returns ``None`` so the real model output reaches the agent unchanged."""
+
+    def __init__(self, *, api_key: str) -> None:
+        super().__init__(name="hexgate_usage")
+        self._api_key = api_key
+
+    async def after_model_callback(
+        self,
+        *,
+        callback_context: CallbackContext,
+        llm_response: LlmResponse,
+    ) -> LlmResponse | None:
+        usage = llm_response.usage_metadata
+        if usage is None:
+            return None
+        emit_llm_usage(
+            callback_context.agent_name,
+            llm_response.model_version or "",
+            usage.prompt_token_count or 0,
+            usage.candidates_token_count or 0,
+            api_key=self._api_key,
+        )
+        return None

{hexgate-0.2.7 → hexgate-0.2.9}/hexgate/adapters/google/wrapper.py

@@ -10,19 +10,25 @@ is what the runner refreshes per run.
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from google.adk.agents import BaseAgent
 
 from hexgate.adapters.google.tools import wrap_tools
-from hexgate.agents.factory import ApprovalHandler
+from hexgate.approvals import ApprovalHandler
 from hexgate.security.binding import PolicyBinding, resolve_policy
 from hexgate.security.enforcer import build_enforcer
 
+if TYPE_CHECKING:
+    from hexgate.cloud.client import HexgateClient
+
 
 def wrap_google_agent(
     agent: BaseAgent,
     *,
     api_key: str,
     approval_handler: ApprovalHandler | None = None,
+    client: HexgateClient | None = None,
 ) -> tuple[BaseAgent, PolicyBinding]:
     """Return a policy-gated clone of ``agent`` plus its refresh binding.
 
@@ -39,7 +45,7 @@ def wrap_google_agent(
     agent_name = getattr(agent, "name", "default")
     tools = list(getattr(agent, "tools", []) or [])
 
-    resolved = resolve_policy(agent_name, api_key=api_key)
+    resolved = resolve_policy(agent_name, api_key=api_key, client=client)
     enforcer = build_enforcer(resolved.engine, agent_name=agent_name, api_key=api_key)
     guarded_tools = wrap_tools(tools, enforcer, approval_handler=approval_handler)
     return (

{hexgate-0.2.7 → hexgate-0.2.9}/hexgate/adapters/langchain/agent.py

@@ -9,9 +9,11 @@ from langfuse import get_client, propagate_attributes
 from langfuse.langchain import CallbackHandler
 from langgraph.graph.state import CompiledStateGraph
 
+from hexgate.adapters.langchain.usage import HexgateUsageCallbackHandler
 from hexgate.runtime import User
 
 if TYPE_CHECKING:
+    from hexgate.security.bans import BanGate
     from hexgate.security.binding import PolicyBinding
 
 
@@ -32,14 +34,20 @@ class HexgateLangchainAgent:
         agent: CompiledStateGraph,
         api_key: str,
         tool_names: list[str],
+        agent_name: str = "default",
         binding: PolicyBinding | None = None,
+        ban_gate: BanGate | None = None,
     ) -> None:
         self._agent = agent
         self._binding = binding
+        self._ban_gate = ban_gate
         self._api_key = api_key
         self._tool_names = tool_names
         self._langfuse = get_client()
         self._callback_handler = CallbackHandler()
+        self._usage_handler = HexgateUsageCallbackHandler(
+            agent_name=agent_name, api_key=api_key
+        )
 
     async def _refresh_async(self) -> None:
         """Refresh the policy binding, if attached (async entry points)."""
@@ -51,6 +59,15 @@ class HexgateLangchainAgent:
         if self._binding is not None:
             self._binding.refresh()
 
+    async def _check_ban_async(self, user: User) -> None:
+        """Refuse a banned agent/user before running, if a gate is attached."""
+        if self._ban_gate is not None:
+            await self._ban_gate.check_async(user)
+
+    def _check_ban(self, user: User) -> None:
+        if self._ban_gate is not None:
+            self._ban_gate.check(user)
+
     def _propagate_kwargs(self, user: User, method: str) -> dict[str, Any]:
         return {
             "tags": [f"langchain.agent.{method}"],
@@ -60,11 +77,12 @@ class HexgateLangchainAgent:
         }
 
     def _with_callbacks(self, config: RunnableConfig | None) -> RunnableConfig:
-        """Append the Hexgate callback handler to ``config['callbacks']``."""
+        """Append the Hexgate callback handlers to ``config['callbacks']``."""
         merged: RunnableConfig = dict(config) if config else {}
         callbacks = list(merged.get("callbacks") or [])
-        if self._callback_handler not in callbacks:
-            callbacks.append(self._callback_handler)
+        for handler in (self._callback_handler, self._usage_handler):
+            if handler not in callbacks:
+                callbacks.append(handler)
         merged["callbacks"] = callbacks
         return merged
 
@@ -78,6 +96,7 @@ class HexgateLangchainAgent:
     ) -> dict[str, Any]:
         """Invoke the agent asynchronously inside a User scope."""
         await self._refresh_async()
+        await self._check_ban_async(user)
         async with user:
             with propagate_attributes(**self._propagate_kwargs(user, "ainvoke")):
                 return await self._agent.ainvoke(
@@ -94,6 +113,7 @@ class HexgateLangchainAgent:
     ) -> dict[str, Any]:
         """Invoke the agent synchronously inside a User scope."""
         self._refresh()
+        self._check_ban(user)
         with user.sync_scope():
             with propagate_attributes(**self._propagate_kwargs(user, "invoke")):
                 return self._agent.invoke(input, self._with_callbacks(config), **kwargs)
@@ -108,6 +128,7 @@ class HexgateLangchainAgent:
     ) -> AsyncIterator[dict[str, Any]]:
         """Stream the agent asynchronously inside a User scope."""
         await self._refresh_async()
+        await self._check_ban_async(user)
         async with user:
             with propagate_attributes(**self._propagate_kwargs(user, "astream")):
                 async for chunk in self._agent.astream(
@@ -125,6 +146,7 @@ class HexgateLangchainAgent:
     ) -> Iterator[dict[str, Any]]:
         """Stream the agent synchronously inside a User scope."""
         self._refresh()
+        self._check_ban(user)
         with user.sync_scope():
             with propagate_attributes(**self._propagate_kwargs(user, "stream")):
                 yield from self._agent.stream(
@@ -142,6 +164,7 @@ class HexgateLangchainAgent:
     ) -> AsyncIterator[dict[str, Any]]:
         """Stream the agent events asynchronously inside a User scope."""
         await self._refresh_async()
+        await self._check_ban_async(user)
         async with user:
             with propagate_attributes(**self._propagate_kwargs(user, "astream_events")):
                 async for event in self._agent.astream_events(
@@ -153,5 +176,10 @@ class HexgateLangchainAgent:
                     yield event
 
     def __getattr__(self, name: str) -> Any:
-        """Delegate unknown attributes to the wrapped agent."""
+        """Delegate unknown attributes to the wrapped agent.
+
+        Only the wrapped run methods (invoke/ainvoke/stream/astream/
+        astream_events) enforce the ban gate + User scope; methods reached
+        here (batch, abatch, astream_log, …) bypass them.
+        """
         return getattr(self._agent, name)

{hexgate-0.2.7 → hexgate-0.2.9}/hexgate/adapters/langchain/tools.py

@@ -26,7 +26,7 @@ from hexgate.agents.approvals import (
 from hexgate.agents.approvals import (
     resolve_approval_sync as _resolve_approval_sync,
 )
-from hexgate.agents.factory import ApprovalHandler
+from hexgate.approvals import ApprovalHandler
 from hexgate.security.decision import DecisionOutcome
 from hexgate.security.enforcer import PolicyEnforcer
 from hexgate.tools.decorators import TOOL_METADATA_ATTR