hexgate 0.2.6__tar.gz → 0.2.8__tar.gz

hexgate-0.2.8/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: hexgate
+Version: 0.2.8
+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
+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.8/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.6 → hexgate-0.2.8}/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.8/hexgate/adapters/google/mcp.py

@@ -0,0 +1,95 @@
+"""Google ADK adapter for :class:`~hexgate.mcp.MCPToolset`.
+
+Every :class:`~hexgate.mcp.MCPToolProxy` produced by the toolset becomes
+a :class:`google.adk.tools.BaseTool` subclass whose ``_get_declaration``
+returns a ``FunctionDeclaration`` carrying the MCP tool's raw
+JSON Schema (via ``parametersJsonSchema``) and whose ``run_async``
+forwards to the proxy's ``call``. Once wrapped, the resulting tools
+are indistinguishable from ADK-native :class:`FunctionTool` instances
+to the rest of the Google ADK path — attach them to an ``Agent``, then
+wrap via :func:`~hexgate.adapters.google.wrap_google_agent` so the
+existing per-tool policy gate covers MCP invocations too.
+
+Usage::
+
+    from google.adk.agents import Agent
+    from hexgate.adapters.google import wrap_google_agent
+    from hexgate.adapters.google.mcp import wrap_mcp_toolset
+    from hexgate.mcp import MCPServerConfig, MCPToolset
+
+    slack = MCPServerConfig(name="slack", transport="stdio", command="slack-mcp")
+    async with MCPToolset(slack) as mcp:
+        agent = Agent(
+            name="bot",
+            tools=[*wrap_mcp_toolset(mcp), *native],
+        )
+        wrapped, binding = wrap_google_agent(agent, api_key=api_key)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from google.adk.tools import BaseTool
+from google.adk.tools.tool_context import ToolContext
+from google.genai import types as genai_types
+
+from hexgate.mcp.proxy import MCPToolProxy, MCPToolset
+
+
+class _MCPProxyTool(BaseTool):
+    """One :class:`BaseTool` that forwards to an :class:`MCPToolProxy`.
+
+    ADK's :class:`FunctionTool` derives its schema from a Python
+    callable's signature via reflection, which can't express the shapes
+    MCP servers advertise (partial ``required``, ``anyOf`` unions,
+    nested objects with dynamic keys). Subclassing :class:`BaseTool`
+    and returning a hand-built :class:`FunctionDeclaration` from
+    ``_get_declaration`` bypasses the reflection path and hands the
+    server's raw JSON Schema straight to the model — via ADK's
+    ``parametersJsonSchema`` alias which accepts JSON Schema dicts.
+    """
+
+    def __init__(self, proxy: MCPToolProxy) -> None:
+        super().__init__(name=proxy.qualified_name, description=proxy.description)
+        # Store the schema + call as private attrs — ADK's BaseTool has
+        # no field for them, so we ride on the object dict.
+        self._input_schema = proxy.input_schema
+        self._call = proxy.call
+
+    def _get_declaration(self) -> genai_types.FunctionDeclaration:
+        # Gemini's FunctionDeclaration validator rejects any
+        # parametersJsonSchema missing a top-level `type` — literal `{}`,
+        # or a partial like `{"properties": {...}}`, or a bare
+        # `{"anyOf": [...]}`. All three shapes cause the whole tool
+        # list to fail at declaration time, so the agent never gets to
+        # run. Fill in `type: "object"` (the only shape Gemini accepts
+        # for a function-args container) whenever it's absent, and
+        # ensure a `properties` map so the LLM sees an argument surface
+        # rather than an opaque object. LangChain and OpenAI Agents
+        # both tolerate the missing `type` unchanged.
+        schema = self._input_schema if isinstance(self._input_schema, dict) else {}
+        if "type" not in schema:
+            schema = {"type": "object", "properties": {}, **schema}
+        return genai_types.FunctionDeclaration(
+            name=self.name,
+            description=self.description,
+            parametersJsonSchema=schema,
+        )
+
+    async def run_async(
+        self, *, args: dict[str, Any], tool_context: ToolContext
+    ) -> Any:
+        return await self._call(**(args or {}))
+
+
+def wrap_mcp_toolset(toolset: MCPToolset) -> list[BaseTool]:
+    """Wrap every proxy in ``toolset`` as a Google ADK :class:`BaseTool`.
+
+    The returned tools share the toolset's connection lifecycle — they
+    stop working (returning a ``use_after_close`` envelope) once the
+    ``async with MCPToolset(...)`` block exits. Combine with
+    :func:`~hexgate.adapters.google.wrap_google_agent` to gate every
+    invocation through :class:`~hexgate.security.PolicyEnforcer`.
+    """
+    return [_MCPProxyTool(p) for p in toolset.proxies]

{hexgate-0.2.6 → hexgate-0.2.8}/hexgate/adapters/google/runner.py

@@ -16,8 +16,11 @@ from langfuse import get_client, propagate_attributes
 from openinference.instrumentation.google_adk import GoogleADKInstrumentor
 
 from hexgate.adapters.google.wrapper import wrap_google_agent
+from hexgate.agents.factory 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:
@@ -30,6 +33,7 @@ class HexgateRunner:
         app_name: str,
         session_service: BaseSessionService,
         api_key: str | None = None,
+        approval_handler: ApprovalHandler | None = None,
         **runner_kwargs: Any,
     ):
         self.api_key = resolve_api_key(api_key)
@@ -39,9 +43,13 @@ 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
+            agent,
+            api_key=self.api_key,
+            approval_handler=approval_handler,
+            client=client,
         )
         self._runner = Runner(
             agent=self._wrapped_agent,
@@ -50,6 +58,9 @@ class HexgateRunner:
             **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)."""
@@ -88,6 +99,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,
@@ -116,6 +129,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.6 → hexgate-0.2.8}/hexgate/adapters/google/tools.py

@@ -1,6 +1,11 @@
 """Google ADK adapter: wrap ``BaseTool`` so ``run_async`` consults a
 :class:`PolicyEnforcer` first. Non-allow outcomes render as markered
 strings the model sees as tool output.
+
+When a caller supplies ``approval_handler``, a ``NEEDS_APPROVAL``
+decision fires the callback and runs the original tool on truthy return;
+falsy return (or a missing handler) keeps today's behavior of surfacing
+the ``[approval_required]`` marker to the model.
 """
 
 from __future__ import annotations
@@ -14,6 +19,9 @@ from google.adk.tools.base_tool import BaseTool
 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.security.decision import DecisionOutcome
 from hexgate.security.enforcer import PolicyEnforcer
 
 
@@ -32,7 +40,12 @@ def _normalize(tool: ToolEntry) -> BaseTool:
     )
 
 
-def wrap_tool(tool: ToolEntry, enforcer: PolicyEnforcer) -> BaseTool:
+def wrap_tool(
+    tool: ToolEntry,
+    enforcer: PolicyEnforcer,
+    *,
+    approval_handler: ApprovalHandler | None = None,
+) -> BaseTool:
     """Return a copy of ``tool`` with ``run_async`` gated by ``enforcer``."""
     base = _normalize(tool)
     name = base.name
@@ -45,6 +58,12 @@ def wrap_tool(tool: ToolEntry, enforcer: PolicyEnforcer) -> BaseTool:
         decision = enforcer.decide(name, args or {})
         if decision.allowed:
             return await original_run_async(args=args, tool_context=tool_context)
+        if (
+            decision.outcome is DecisionOutcome.NEEDS_APPROVAL
+            and approval_handler is not None
+            and await resolve_approval_async(approval_handler, decision)
+        ):
+            return await original_run_async(args=args, tool_context=tool_context)
         return decision.as_error_message()
 
     wrapped = copy.copy(base)
@@ -52,6 +71,11 @@ def wrap_tool(tool: ToolEntry, enforcer: PolicyEnforcer) -> BaseTool:
     return wrapped
 
 
-def wrap_tools(tools: list[ToolEntry], enforcer: PolicyEnforcer) -> list[BaseTool]:
+def wrap_tools(
+    tools: list[ToolEntry],
+    enforcer: PolicyEnforcer,
+    *,
+    approval_handler: ApprovalHandler | None = None,
+) -> list[BaseTool]:
     """Return a fresh list of policy-gated copies."""
-    return [wrap_tool(t, enforcer) for t in tools]
+    return [wrap_tool(t, enforcer, approval_handler=approval_handler) for t in tools]

{hexgate-0.2.6 → hexgate-0.2.8}/hexgate/adapters/google/wrapper.py

@@ -10,31 +10,44 @@ 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.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
+    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.
 
     Caller must open a :class:`User` scope around the run.
-    ``NEEDS_APPROVAL`` outcomes surface as ``[approval_required]``-prefixed
-    strings in tool results; ``[policy_denied]`` for denials. Refresh the
-    returned binding at run boundaries (``HexgateRunner`` does). Fail-loud:
-    an unregistered agent (platform 404) raises — register it first with
+    ``NEEDS_APPROVAL`` outcomes fire ``approval_handler`` (async
+    ``fn(decision) -> bool`` or ``bool`` shorthand); a truthy return
+    runs the tool, falsy or missing handler surfaces the
+    ``[approval_required]``-prefixed string as tool result.
+    ``[policy_denied]`` marks plain denials. Refresh the returned
+    binding at run boundaries (``HexgateRunner`` does). Fail-loud: an
+    unregistered agent (platform 404) raises — register it first with
     ``hexgate register``.
     """
     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)
+    guarded_tools = wrap_tools(tools, enforcer, approval_handler=approval_handler)
     return (
         agent.model_copy(update={"tools": guarded_tools}),
         PolicyBinding(enforcer, resolved.source),