agentguardproxy 0.6.0__tar.gz → 1.0.0__tar.gz

{agentguardproxy-0.6.0 → agentguardproxy-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentguardproxy
-Version: 0.6.0
+Version: 1.0.0
 Summary: Python SDK for AgentGuard — the firewall for AI agents
 Author-email: Cauã Ferraz <cauaferrazp@gmail.com>
 License-Expression: Apache-2.0

agentguardproxy-1.0.0/agentguard/__init__.py

@@ -0,0 +1,89 @@
+"""
+AgentGuard Python SDK
+
+Lightweight client for checking actions against AgentGuard policies.
+
+Usage:
+    from agentguard import Guard
+
+    guard = Guard("http://localhost:8080")
+    result = guard.check("shell", command="rm -rf ./data")
+
+    if result.allowed:
+        execute(command)
+    elif result.needs_approval:
+        print(f"Approve at: {result.approval_url}")
+    else:
+        print(f"Blocked: {result.reason}")
+
+Layout: the :class:`Guard` client, :class:`CheckResult`, exceptions and
+constants live in :mod:`agentguard.core`; the ``@guarded`` decorator in
+:mod:`agentguard.decorators`; framework integrations in
+:mod:`agentguard.adapters`. Everything public is re-exported here —
+import from the package root.
+"""
+
+# Back-compat module aliases. The pre-split __init__ imported these
+# stdlib modules directly, which made e.g. ``agentguard.request`` and
+# ``agentguard.time`` valid mock.patch targets ("agentguard.request.
+# urlopen", "agentguard.time.sleep", ...). Patching through these names
+# mutates the shared stdlib module, so it intercepts agentguard.core's
+# calls exactly as it did before the split. Do not remove without a
+# deprecation cycle.
+import functools  # noqa: F401
+import json  # noqa: F401
+import logging  # noqa: F401
+import os  # noqa: F401
+import random  # noqa: F401
+import time  # noqa: F401
+from urllib import request, error  # noqa: F401
+from urllib.parse import quote as urlquote  # noqa: F401
+
+from agentguard.core import (
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    DEFAULT_APPROVAL_TIMEOUT,
+    DEFAULT_POLL_INTERVAL,
+    DECISION_ALLOW,
+    DECISION_DENY,
+    DECISION_REQUIRE_APPROVAL,
+    ENDPOINT_CHECK,
+    ENDPOINT_APPROVE,
+    ENDPOINT_DENY,
+    ENDPOINT_STATUS,
+    LOCAL_TENANT_ID,
+    FAIL_MODE_DENY,
+    FAIL_MODE_ALLOW,
+    AgentGuardError,
+    AgentGuardDenied,
+    AgentGuardApprovalRequired,
+    AgentGuardApprovalTimeout,
+    AgentGuardAuthError,
+    AgentGuardTimeoutError,
+    CheckResult,
+    Guard,
+    log,
+)
+from agentguard.decorators import guarded
+
+# Public API surface. Everything else is internal.
+__all__ = [
+    "Guard",
+    "CheckResult",
+    "guarded",
+    "AgentGuardError",
+    "AgentGuardDenied",
+    "AgentGuardApprovalRequired",
+    "AgentGuardApprovalTimeout",
+    "AgentGuardAuthError",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TIMEOUT",
+    "DEFAULT_APPROVAL_TIMEOUT",
+    "DEFAULT_POLL_INTERVAL",
+    "DECISION_ALLOW",
+    "DECISION_DENY",
+    "DECISION_REQUIRE_APPROVAL",
+    "LOCAL_TENANT_ID",
+    "FAIL_MODE_DENY",
+    "FAIL_MODE_ALLOW",
+]

agentguardproxy-1.0.0/agentguard/adapters/_common.py

@@ -0,0 +1,99 @@
+"""Shared check-parameter extraction for the framework adapters.
+
+LangChain, CrewAI and MCP all reduce a tool invocation to the same
+``Guard.check`` keyword arguments (command, url, domain, path, action,
+session_id, est_cost). The extraction lives here once so the adapters
+cannot drift apart; each adapter keeps only its framework-specific
+glue (input normalisation, error surfacing, redaction).
+"""
+
+from typing import Any
+from urllib.parse import urlparse
+
+
+def domain_from_url(url: Any) -> str:
+    """Best-effort hostname extraction; "" when absent or malformed."""
+    if not isinstance(url, str):
+        return ""
+    try:
+        return urlparse(url).hostname or ""
+    except Exception:
+        return ""
+
+
+# Filesystem-action verb groups. These MUST stay byte-identical to the Go
+# transports' gateclient.InferFilesystemAction (pkg/internal/gateclient/
+# gateclient.go): same verbs, same groups, same precedence (read, then
+# write, then delete). Parity is pinned by two mirrored test tables —
+# plugins/python/tests/test_action_parity.py and
+# pkg/internal/gateclient/gateclient_test.go. Edit both sides together.
+_READ_PREFIXES = ("read", "list", "get", "stat", "cat", "find", "glob")
+_WRITE_PREFIXES = ("write", "edit", "create", "append", "save", "copy", "move")
+_DELETE_PREFIXES = ("delete", "remove", "unlink", "rm")
+
+
+def infer_path_action(tool_name: Any) -> str:
+    """Map a tool-name verb to the canonical filesystem action
+    ("read"/"write"/"delete"), or "" when no verb matches.
+
+    Mirrors the Go transports' gateclient.InferFilesystemAction exactly:
+    a case-insensitive ``strings.HasPrefix`` (Python ``str.startswith``)
+    against these verb groups, checked in this order —
+
+        read   = read, list, get, stat, cat, find, glob
+        write  = write, edit, create, append, save, copy, move
+        delete = delete, remove, unlink, rm
+
+    Prefix (not substring) matching is deliberate: it avoids the false
+    positives substring matching produces that Go never makes — e.g.
+    "set_target" contains "get" but does not START with it, and
+    "undelete_x" contains "delete" but does not start with it. Both
+    correctly yield "" here, matching Go. Parity is pinned by
+    plugins/python/tests/test_action_parity.py, whose table mirrors
+    pkg/internal/gateclient/gateclient_test.go.
+    """
+    if not isinstance(tool_name, str):
+        return ""
+    name_lower = tool_name.lower()
+    if name_lower.startswith(_READ_PREFIXES):
+        return "read"
+    if name_lower.startswith(_WRITE_PREFIXES):
+        return "write"
+    if name_lower.startswith(_DELETE_PREFIXES):
+        return "delete"
+    return ""
+
+
+def extract_check_params(tool_input: Any, tool_name: Any = None) -> dict:
+    """Reduce a str/dict tool input to ``Guard.check`` keyword params.
+
+    A bare string is treated as a shell command. For dicts, recognised
+    keys are projected (command/cmd, url + derived domain,
+    path/file_path + action inferred from the tool-name verb,
+    session_id, est_cost); everything else is ignored.
+    """
+    params: dict = {}
+    if isinstance(tool_input, str):
+        params["command"] = tool_input
+    elif isinstance(tool_input, dict):
+        if "command" in tool_input or "cmd" in tool_input:
+            params["command"] = tool_input.get(
+                "command", tool_input.get("cmd", "")
+            )
+        if "url" in tool_input:
+            params["url"] = tool_input["url"]
+            domain = domain_from_url(tool_input["url"])
+            if domain:
+                params["domain"] = domain
+        if "path" in tool_input or "file_path" in tool_input:
+            params["path"] = tool_input.get(
+                "path", tool_input.get("file_path", "")
+            )
+            action = infer_path_action(tool_name)
+            if action:
+                params["action"] = action
+        if "session_id" in tool_input:
+            params["session_id"] = tool_input["session_id"]
+        if "est_cost" in tool_input:
+            params["est_cost"] = tool_input["est_cost"]
+    return params

{agentguardproxy-0.6.0 → agentguardproxy-1.0.0}/agentguard/adapters/crewai.py

@@ -68,6 +68,7 @@ from agentguard import (
     AgentGuardDenied,
     Guard,
 )
+from agentguard.adapters._common import extract_check_params
 
 
 # ---------------------------------------------------------------------------
@@ -226,32 +227,7 @@ def _build_guarded_class() -> type:
 
         def _extract_check_params(self, tool_input: Any) -> dict:
             """Extract check params from str/dict tool input."""
-            params: dict = {}
-            if isinstance(tool_input, str):
-                params["command"] = tool_input
-            elif isinstance(tool_input, dict):
-                if "command" in tool_input or "cmd" in tool_input:
-                    params["command"] = tool_input.get(
-                        "command", tool_input.get("cmd", "")
-                    )
-                if "url" in tool_input:
-                    params["url"] = tool_input["url"]
-                    try:
-                        from urllib.parse import urlparse
-                        parsed = urlparse(tool_input["url"])
-                        if parsed.hostname:
-                            params["domain"] = parsed.hostname
-                    except Exception:
-                        pass
-                if "path" in tool_input or "file_path" in tool_input:
-                    params["path"] = tool_input.get(
-                        "path", tool_input.get("file_path", "")
-                    )
-                if "session_id" in tool_input:
-                    params["session_id"] = tool_input["session_id"]
-                if "est_cost" in tool_input:
-                    params["est_cost"] = tool_input["est_cost"]
-            return params
+            return extract_check_params(tool_input, self.name)
 
         # ----------------------------------------------------------
         # The single shared gate.

{agentguardproxy-0.6.0 → agentguardproxy-1.0.0}/agentguard/adapters/langchain.py

@@ -24,8 +24,8 @@ entry point the framework calls is explicitly overridden:
   - ``invoke`` / ``ainvoke`` — overridden anyway so the gate fires
     even if a future framework version short-circuits the parent's
     invoke -> run -> _run chain.
-  - ``stream`` / ``astream`` — gated once at stream open; per-chunk
-    gating is a v0.6 issue.
+  - ``stream`` / ``astream`` — gated at stream open + periodic
+    re-validation (see "Stream gating" below).
   - ``batch`` / ``abatch`` — gate each input independently; first DENY
     raises for the whole batch (whole-batch-fails-on-first-deny).
   - ``run`` / ``arun`` — legacy entries; preserve string-on-deny
@@ -46,19 +46,30 @@ extra. The class definition is wrapped in a builder that resolves
 the ``GuardedTool`` symbol is a callable factory that raises a clear
 ``ImportError`` when constructed.
 
-Stream gating limitation
-========================
+Stream gating
+=============
 
-For ``stream`` / ``astream`` the gate fires **once** at stream open.
-Mid-stream tool calls bypass the gate. TODO(v0.6): per-chunk gating
-in ``stream()`` / ``astream()``.
+``stream`` / ``astream`` gate at stream open and re-validate the
+decision every ``STREAM_REGATE_SECONDS`` (default 10s) while chunks
+flow, so a mid-stream policy revocation cuts the stream off instead of
+riding to completion.
 """
 
 from __future__ import annotations
 
+import time
 from typing import Any, AsyncIterator, Iterator, List, Optional
 
 from agentguard import Guard, CheckResult, DEFAULT_BASE_URL
+from agentguard.adapters._common import extract_check_params
+
+# How often a live stream re-validates its policy decision. Streams gate
+# at open; without re-validation a long-lived stream would ride to
+# completion even after a policy hot-reload revoked the permission.
+# Re-checking costs one local /v1/check HTTP round-trip, so it runs on a
+# wall-clock interval rather than per chunk. Tests shrink this to force
+# a re-check on every chunk.
+STREAM_REGATE_SECONDS = 10.0
 
 
 # ---------------------------------------------------------------------------
@@ -177,39 +188,7 @@ def _build_guarded_tool_class() -> type:
 
         def _infer_check_params(self, tool_input: Any) -> dict:
             """Extract meaningful parameters from tool input."""
-            params: dict = {}
-            if isinstance(tool_input, str):
-                params["command"] = tool_input
-            elif isinstance(tool_input, dict):
-                if "command" in tool_input or "cmd" in tool_input:
-                    params["command"] = tool_input.get(
-                        "command", tool_input.get("cmd", "")
-                    )
-                if "url" in tool_input:
-                    params["url"] = tool_input["url"]
-                    try:
-                        from urllib.parse import urlparse
-                        parsed = urlparse(tool_input["url"])
-                        if parsed.hostname:
-                            params["domain"] = parsed.hostname
-                    except Exception:
-                        pass
-                if "path" in tool_input or "file_path" in tool_input:
-                    params["path"] = tool_input.get(
-                        "path", tool_input.get("file_path", "")
-                    )
-                    name_lower = self.name.lower() if isinstance(self.name, str) else ""
-                    if "read" in name_lower or "get" in name_lower:
-                        params["action"] = "read"
-                    elif "write" in name_lower or "save" in name_lower or "create" in name_lower:
-                        params["action"] = "write"
-                    elif "delete" in name_lower or "remove" in name_lower:
-                        params["action"] = "delete"
-                if "session_id" in tool_input:
-                    params["session_id"] = tool_input["session_id"]
-                if "est_cost" in tool_input:
-                    params["est_cost"] = tool_input["est_cost"]
-            return params
+            return extract_check_params(tool_input, self.name)
 
         def _infer_scope(self, params: dict) -> str:
             if params.get("domain") or params.get("url"):
@@ -421,12 +400,27 @@ def _build_guarded_tool_class() -> type:
             config: Any = None,
             **kwargs: Any,
         ) -> Iterator[Any]:
-            """Synchronous streaming Runnable entry. Gate fires once at
-            stream open. TODO(v0.6): gate per chunk."""
+            """Synchronous streaming Runnable entry. Gates at stream
+            open, then re-validates every ``STREAM_REGATE_SECONDS``
+            while chunks flow — a policy change mid-stream (permission
+            revoked via hot-reload) cuts the stream off with the same
+            typed ``PermissionError`` instead of riding to completion.
+            """
             result = self._gate(input)
             self._raise_for_modern_api(result, input)
             inner = self._tool
-            return inner.stream(input, config=config, **kwargs)
+
+            def guarded_chunks() -> Iterator[Any]:
+                last_check = time.monotonic()
+                for chunk in inner.stream(input, config=config, **kwargs):
+                    now = time.monotonic()
+                    if now - last_check >= STREAM_REGATE_SECONDS:
+                        recheck = self._gate(input)
+                        self._raise_for_modern_api(recheck, input)
+                        last_check = now
+                    yield chunk
+
+            return guarded_chunks()
 
         async def astream(  # type: ignore[override]
             self,
@@ -434,11 +428,18 @@ def _build_guarded_tool_class() -> type:
             config: Any = None,
             **kwargs: Any,
         ) -> AsyncIterator[Any]:
-            """Async streaming Runnable entry. Same one-shot gate."""
+            """Async streaming Runnable entry. Same open-gate +
+            periodic re-validation contract as :meth:`stream`."""
             result = self._gate(input)
             self._raise_for_modern_api(result, input)
             inner = self._tool
+            last_check = time.monotonic()
             async for chunk in inner.astream(input, config=config, **kwargs):
+                now = time.monotonic()
+                if now - last_check >= STREAM_REGATE_SECONDS:
+                    recheck = self._gate(input)
+                    self._raise_for_modern_api(recheck, input)
+                    last_check = now
                 yield chunk
 
         def batch(  # type: ignore[override]

{agentguardproxy-0.6.0 → agentguardproxy-1.0.0}/agentguard/adapters/mcp.py

@@ -37,10 +37,11 @@ import re
 import sys
 from typing import Any, Callable, Dict, List, Optional
 from agentguard import Guard, CheckResult, DEFAULT_BASE_URL
+from agentguard.adapters._common import extract_check_params
 
 # MCP protocol constants
 MCP_PROTOCOL_VERSION = "2024-11-05"
-SDK_VERSION = "0.6.0"
+SDK_VERSION = "1.0.0"
 
 # Secret patterns mirrored from pkg/notify/notify.go's DefaultRedactor. The
 # MCP adapter forwards handler exception text back to the client as a
@@ -77,46 +78,24 @@ def _infer_check_params_for(tool: "ToolDefinition", arguments: dict) -> dict:
     redaction. Defining the logic once at module scope keeps the gateway
     from awkwardly invoking the unbound server method on a non-server
     ``self`` (the gateway is its own class).
-    """
-    from urllib.parse import urlparse  # local import — only used here
 
-    params: Dict[str, Any] = {}
+    Builds on the shared :func:`extract_check_params` and adds the
+    MCP-specific parts: secret redaction on commands, a synthesised
+    command for shell-scope tools without an explicit one, and a bare
+    ``domain`` argument passthrough.
+    """
+    params: Dict[str, Any] = extract_check_params(arguments, tool.name)
 
-    if "command" in arguments or "cmd" in arguments:
-        raw_cmd = arguments.get("command", arguments.get("cmd", ""))
-        params["command"] = _redact(raw_cmd) if isinstance(raw_cmd, str) else raw_cmd
+    if "command" in params:
+        cmd = params["command"]
+        if isinstance(cmd, str):
+            params["command"] = _redact(cmd)
     elif tool.scope == "shell":
         params["command"] = _redact(f"{tool.name} {json.dumps(arguments)}")
 
-    if "url" in arguments:
-        params["url"] = arguments["url"]
-        try:
-            parsed = urlparse(arguments["url"])
-            if parsed.hostname:
-                params["domain"] = parsed.hostname
-        except Exception:
-            # urlparse practically never raises but defensive — a malformed
-            # URL must not crash the policy check.
-            pass
-
-    if "path" in arguments or "file_path" in arguments:
-        params["path"] = arguments.get("path", arguments.get("file_path", ""))
-        name_lower = tool.name.lower()
-        if "read" in name_lower or "get" in name_lower:
-            params["action"] = "read"
-        elif "write" in name_lower or "save" in name_lower:
-            params["action"] = "write"
-        elif "delete" in name_lower or "remove" in name_lower:
-            params["action"] = "delete"
-
     if "domain" in arguments:
         params["domain"] = arguments["domain"]
 
-    if "session_id" in arguments:
-        params["session_id"] = arguments["session_id"]
-    if "est_cost" in arguments:
-        params["est_cost"] = arguments["est_cost"]
-
     return params
 
 

agentguardproxy-0.6.0/agentguard/__init__.py → agentguardproxy-1.0.0/agentguard/core.py

@@ -1,33 +1,21 @@
+"""Core AgentGuard SDK: the :class:`Guard` HTTP client, the
+:class:`CheckResult` decision shape, the typed exceptions, and the
+wire-level constants. Import from the ``agentguard`` package root —
+this module is an implementation detail; the package ``__init__``
+re-exports the public surface.
 """
-AgentGuard Python SDK
 
-Lightweight client for checking actions against AgentGuard policies.
-
-Usage:
-    from agentguard import Guard
-
-    guard = Guard("http://localhost:8080")
-    result = guard.check("shell", command="rm -rf ./data")
-
-    if result.allowed:
-        execute(command)
-    elif result.needs_approval:
-        print(f"Approve at: {result.approval_url}")
-    else:
-        print(f"Blocked: {result.reason}")
-"""
-
-import functools
 import json
 import logging
 import os
 import random
 import time
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from typing import Optional
 from urllib import request, error
 from urllib.parse import quote as urlquote
 
+
 # Module-level logger. Used for non-fatal warnings (HTTP shape mismatches,
 # unexpected content types) where the SDK still returns a CheckResult per
 # the configured fail-mode but operators want visibility into the underlying
@@ -510,126 +498,3 @@ class Guard:
             time.sleep(actual_sleep)
 
         return CheckResult(decision=DECISION_DENY, reason="Approval timed out")
-
-
-# Set of kwargs that ``guarded(**check_kwargs)`` is allowed to forward to
-# ``Guard.check``. Anything outside this set is almost always a typo
-# (e.g. ``agent="x"`` instead of ``meta={"agent":"x"}``) — and silently
-# forwarding it to ``Guard.check`` would either be dropped on the floor
-# (``check`` only inspects keyword args it knows about) or raise a
-# confusing TypeError much later in the call chain. Reject at the
-# decorator boundary so the typo surfaces at definition time.
-_GUARDED_VALID_CHECK_KWARGS = frozenset({
-    "action",
-    "command",
-    "path",
-    "domain",
-    "url",
-    "session_id",
-    "est_cost",
-    "meta",
-})
-
-
-# Convenience decorator for guarding functions
-def guarded(
-    scope: str,
-    guard: Optional[Guard] = None,
-    *,
-    wait_for_approval: bool = False,
-    approval_timeout: int = DEFAULT_APPROVAL_TIMEOUT,
-    approval_poll_interval: int = DEFAULT_POLL_INTERVAL,
-    **check_kwargs,
-):
-    """Decorator that checks policy before executing a function.
-
-    Default behavior (v0.4.0/v0.4.1 compatible):
-        @guarded("shell", guard=guard)
-        def run_command(cmd: str):
-            os.system(cmd)
-
-        run_command("ls")        # executes if ALLOW
-        run_command("rm -rf /")  # raises AgentGuardDenied (a PermissionError)
-
-    Opt-in block-until-resolved:
-        @guarded(
-            "cost",
-            guard=guard,
-            wait_for_approval=True,
-            approval_timeout=300,
-            approval_poll_interval=2,
-        )
-        def expensive_call(prompt: str):
-            ...
-
-    On REQUIRE_APPROVAL, with ``wait_for_approval=True`` the wrapper calls
-    :meth:`Guard.wait_for_approval` and then dispatches on the resolved
-    decision: ALLOW runs the function, DENY raises :class:`AgentGuardDenied`,
-    a synthetic "Approval timed out" raises :class:`AgentGuardApprovalTimeout`.
-    With ``wait_for_approval=False`` (default), the wrapper raises
-    :class:`AgentGuardApprovalRequired` immediately. That class extends
-    ``PermissionError``, so existing ``except PermissionError:`` handlers
-    continue to work unchanged.
-
-    Unknown ``**check_kwargs`` raise ``TypeError`` at decoration time.
-    Only the keyword arguments :meth:`Guard.check` understands
-    (``action``, ``command``, ``path``, ``domain``, ``url``,
-    ``session_id``, ``est_cost``, ``meta``) are accepted; a typo like
-    ``agent="x"`` is rejected at definition time rather than silently
-    dropped.
-    """
-    unknown = set(check_kwargs) - _GUARDED_VALID_CHECK_KWARGS
-    if unknown:
-        raise TypeError(
-            f"@guarded got unexpected keyword arguments: "
-            f"{sorted(unknown)!r}. Valid options: "
-            f"{sorted(_GUARDED_VALID_CHECK_KWARGS)!r}"
-        )
-
-    def decorator(func):
-        @functools.wraps(func)
-        def wrapper(*args, **kwargs):
-            g = guard or Guard()
-            # Try to extract meaningful info from args
-            cmd = args[0] if args else kwargs.get("command", kwargs.get("cmd", ""))
-            result = g.check(scope, command=str(cmd), **check_kwargs)
-
-            if result.allowed:
-                return func(*args, **kwargs)
-
-            if result.needs_approval:
-                if wait_for_approval:
-                    # Block until a human resolves or the deadline elapses.
-                    resolved = g.wait_for_approval(
-                        result.approval_id,
-                        timeout=approval_timeout,
-                        poll_interval=approval_poll_interval,
-                    )
-                    if resolved.allowed:
-                        return func(*args, **kwargs)
-                    if resolved.denied and resolved.reason == "Approval timed out":
-                        raise AgentGuardApprovalTimeout(
-                            f"Approval for {result.approval_id} timed out after "
-                            f"{approval_timeout}s",
-                            result=resolved,
-                            approval_id=result.approval_id,
-                        )
-                    raise AgentGuardDenied(
-                        f"Action denied by AgentGuard: {resolved.reason}",
-                        result=resolved,
-                    )
-                raise AgentGuardApprovalRequired(
-                    # Stable message text — text-matchers in caller code
-                    # depend on it.
-                    f"Action requires approval. Approve at: {result.approval_url}",
-                    result=result,
-                    approval_id=result.approval_id,
-                    approval_url=result.approval_url,
-                )
-
-            raise AgentGuardDenied(
-                f"Action denied by AgentGuard: {result.reason}",
-                result=result,
-            )
-        return wrapper
-    return decorator

agentguardproxy-1.0.0/agentguard/decorators.py

@@ -0,0 +1,138 @@
+"""The ``@guarded`` decorator: policy-check-then-call for plain
+functions. Framework-specific integration lives in
+``agentguard.adapters``; this module only depends on the core client.
+"""
+
+import functools
+from typing import Optional
+
+from agentguard.core import (
+    DEFAULT_APPROVAL_TIMEOUT,
+    DEFAULT_POLL_INTERVAL,
+    AgentGuardApprovalRequired,
+    AgentGuardApprovalTimeout,
+    AgentGuardDenied,
+    Guard,
+)
+
+# Set of kwargs that ``guarded(**check_kwargs)`` is allowed to forward to
+# ``Guard.check``. Anything outside this set is almost always a typo
+# (e.g. ``agent="x"`` instead of ``meta={"agent":"x"}``) — and silently
+# forwarding it to ``Guard.check`` would either be dropped on the floor
+# (``check`` only inspects keyword args it knows about) or raise a
+# confusing TypeError much later in the call chain. Reject at the
+# decorator boundary so the typo surfaces at definition time.
+_GUARDED_VALID_CHECK_KWARGS = frozenset({
+    "action",
+    "command",
+    "path",
+    "domain",
+    "url",
+    "session_id",
+    "est_cost",
+    "meta",
+})
+
+
+# Convenience decorator for guarding functions
+def guarded(
+    scope: str,
+    guard: Optional[Guard] = None,
+    *,
+    wait_for_approval: bool = False,
+    approval_timeout: int = DEFAULT_APPROVAL_TIMEOUT,
+    approval_poll_interval: int = DEFAULT_POLL_INTERVAL,
+    **check_kwargs,
+):
+    """Decorator that checks policy before executing a function.
+
+    Default behavior (v0.4.0/v0.4.1 compatible):
+        @guarded("shell", guard=guard)
+        def run_command(cmd: str):
+            os.system(cmd)
+
+        run_command("ls")        # executes if ALLOW
+        run_command("rm -rf /")  # raises AgentGuardDenied (a PermissionError)
+
+    Opt-in block-until-resolved:
+        @guarded(
+            "cost",
+            guard=guard,
+            wait_for_approval=True,
+            approval_timeout=300,
+            approval_poll_interval=2,
+        )
+        def expensive_call(prompt: str):
+            ...
+
+    On REQUIRE_APPROVAL, with ``wait_for_approval=True`` the wrapper calls
+    :meth:`Guard.wait_for_approval` and then dispatches on the resolved
+    decision: ALLOW runs the function, DENY raises :class:`AgentGuardDenied`,
+    a synthetic "Approval timed out" raises :class:`AgentGuardApprovalTimeout`.
+    With ``wait_for_approval=False`` (default), the wrapper raises
+    :class:`AgentGuardApprovalRequired` immediately. That class extends
+    ``PermissionError``, so existing ``except PermissionError:`` handlers
+    continue to work unchanged.
+
+    Unknown ``**check_kwargs`` raise ``TypeError`` at decoration time.
+    Only the keyword arguments :meth:`Guard.check` understands
+    (``action``, ``command``, ``path``, ``domain``, ``url``,
+    ``session_id``, ``est_cost``, ``meta``) are accepted; a typo like
+    ``agent="x"`` is rejected at definition time rather than silently
+    dropped.
+    """
+    unknown = set(check_kwargs) - _GUARDED_VALID_CHECK_KWARGS
+    if unknown:
+        raise TypeError(
+            f"@guarded got unexpected keyword arguments: "
+            f"{sorted(unknown)!r}. Valid options: "
+            f"{sorted(_GUARDED_VALID_CHECK_KWARGS)!r}"
+        )
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            g = guard or Guard()
+            # Try to extract meaningful info from args
+            cmd = args[0] if args else kwargs.get("command", kwargs.get("cmd", ""))
+            result = g.check(scope, command=str(cmd), **check_kwargs)
+
+            if result.allowed:
+                return func(*args, **kwargs)
+
+            if result.needs_approval:
+                if wait_for_approval:
+                    # Block until a human resolves or the deadline elapses.
+                    resolved = g.wait_for_approval(
+                        result.approval_id,
+                        timeout=approval_timeout,
+                        poll_interval=approval_poll_interval,
+                    )
+                    if resolved.allowed:
+                        return func(*args, **kwargs)
+                    if resolved.denied and resolved.reason == "Approval timed out":
+                        raise AgentGuardApprovalTimeout(
+                            f"Approval for {result.approval_id} timed out after "
+                            f"{approval_timeout}s",
+                            result=resolved,
+                            approval_id=result.approval_id,
+                        )
+                    raise AgentGuardDenied(
+                        f"Action denied by AgentGuard: {resolved.reason}",
+                        result=resolved,
+                    )
+                raise AgentGuardApprovalRequired(
+                    # Stable message text — text-matchers in caller code
+                    # depend on it.
+                    f"Action requires approval. Approve at: {result.approval_url}",
+                    result=result,
+                    approval_id=result.approval_id,
+                    approval_url=result.approval_url,
+                )
+
+            raise AgentGuardDenied(
+                f"Action denied by AgentGuard: {result.reason}",
+                result=result,
+            )
+        return wrapper
+    return decorator

{agentguardproxy-0.6.0 → agentguardproxy-1.0.0}/agentguardproxy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentguardproxy
-Version: 0.6.0
+Version: 1.0.0
 Summary: Python SDK for AgentGuard — the firewall for AI agents
 Author-email: Cauã Ferraz <cauaferrazp@gmail.com>
 License-Expression: Apache-2.0

{agentguardproxy-0.6.0 → agentguardproxy-1.0.0}/agentguardproxy.egg-info/SOURCES.txt

@@ -1,7 +1,10 @@
 README.md
 pyproject.toml
 agentguard/__init__.py
+agentguard/core.py
+agentguard/decorators.py
 agentguard/adapters/__init__.py
+agentguard/adapters/_common.py
 agentguard/adapters/browseruse.py
 agentguard/adapters/crewai.py
 agentguard/adapters/langchain.py
@@ -11,6 +14,7 @@ agentguardproxy.egg-info/SOURCES.txt
 agentguardproxy.egg-info/dependency_links.txt
 agentguardproxy.egg-info/requires.txt
 agentguardproxy.egg-info/top_level.txt
+tests/test_action_parity.py
 tests/test_adapters.py
 tests/test_adapters_extended.py
 tests/test_browseruse.py

{agentguardproxy-0.6.0 → agentguardproxy-1.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentguardproxy"
-version = "0.6.0"
+version = "1.0.0"
 description = "Python SDK for AgentGuard — the firewall for AI agents"
 readme = "README.md"
 license = "Apache-2.0"

agentguardproxy-1.0.0/tests/test_action_parity.py

@@ -0,0 +1,113 @@
+"""Filesystem-action inference parity: Python SDK <-> Go transports.
+
+The Python adapters (infer_path_action in agentguard.adapters._common) and
+the Go transports (gateclient.InferFilesystemAction) must map a tool name to
+the SAME filesystem `action` ("read"/"write"/"delete"/""), otherwise an
+`action:`-keyed filesystem policy rule fires on one transport and not the
+other for the same tool call.
+
+The table below is the SAME (tool_name -> action) table pinned on the Go
+side in pkg/internal/gateclient/gateclient_test.go (TestInferFilesystemAction).
+When you add or change a verb in one place, change it in the other and update
+BOTH tables — this test and that Go test are the tripwire.
+
+This module imports ONLY agentguard.adapters._common, so it runs without
+langchain / crewai / mcp (or any framework dependency) installed.
+"""
+
+from agentguard.adapters._common import infer_path_action
+
+
+# Mirror of gateclient_test.go's TestInferFilesystemAction table. Keep in sync.
+GO_PARITY_TABLE = {
+    "read_file": "read",
+    "list_files": "read",
+    "get_file": "read",
+    "stat_file": "read",
+    "cat": "read",
+    "find_files": "read",
+    "glob": "read",
+    "write_file": "write",
+    "edit_file": "write",
+    "create_dir": "write",
+    "append_file": "write",
+    "delete_file": "delete",
+    "remove_dir": "delete",
+    "unlink": "delete",
+    "unknown": "",
+}
+
+# Extra regression cases for verbs the substring implementation used to miss
+# (edit/append/copy/move/unlink/rm*/list/stat/cat/find/glob). These are the
+# tool names that previously sent NO action through the Python SDK while the
+# Go transports DID send one.
+REGRESSION_TABLE = {
+    "edit_file": "write",
+    "append_file": "write",
+    "copy_file": "write",
+    "move_file": "write",
+    "unlink": "delete",
+    "rmdir": "delete",  # "rm" prefix
+    "rm": "delete",
+    "list_files": "read",
+    "stat_file": "read",
+    "cat": "read",
+    "find_files": "read",
+    "glob": "read",
+}
+
+# False-positive guards: substring matching (the old behavior) wrongly mapped
+# these; prefix matching (Go's HasPrefix, our str.startswith) does not.
+FALSE_POSITIVE_TABLE = {
+    "set_target": "",   # contains "get" but does not START with it
+    "undelete_x": "",   # contains "delete" but does not START with it
+    "forget": "",       # contains "get"
+    "overwrite": "",    # contains "write"
+}
+
+
+def test_go_parity_table():
+    """Every pinned Go case maps identically in Python."""
+    for tool_name, expected in GO_PARITY_TABLE.items():
+        assert infer_path_action(tool_name) == expected, (
+            f"infer_path_action({tool_name!r}) diverged from Go parity table"
+        )
+
+
+def test_regression_cases_previously_missed_by_substring():
+    for tool_name, expected in REGRESSION_TABLE.items():
+        assert infer_path_action(tool_name) == expected, (
+            f"infer_path_action({tool_name!r}) regressed"
+        )
+
+
+def test_false_positive_guards():
+    for tool_name, expected in FALSE_POSITIVE_TABLE.items():
+        assert infer_path_action(tool_name) == expected, (
+            f"infer_path_action({tool_name!r}) should be {expected!r} "
+            f"(prefix, not substring, matching)"
+        )
+
+
+def test_non_string_input_is_empty():
+    for bad in (None, 123, ["read_file"], {"name": "read_file"}, object()):
+        assert infer_path_action(bad) == ""
+
+
+def test_case_insensitive():
+    # HasPrefix is applied to strings.ToLower(toolName) on the Go side; we
+    # lowercase too, so mixed case still resolves.
+    assert infer_path_action("READ_File") == "read"
+    assert infer_path_action("Write_Thing") == "write"
+    assert infer_path_action("DELETE_it") == "delete"
+
+
+if __name__ == "__main__":
+    # Allow a framework-free smoke run without pytest installed.
+    for table in (GO_PARITY_TABLE, REGRESSION_TABLE, FALSE_POSITIVE_TABLE):
+        for name, want in table.items():
+            got = infer_path_action(name)
+            assert got == want, f"{name!r}: got {got!r}, want {want!r}"
+    for bad in (None, 123, ["x"], {"a": 1}):
+        assert infer_path_action(bad) == ""
+    print("action-parity smoke OK")

{agentguardproxy-0.6.0 → agentguardproxy-1.0.0}/tests/test_langchain.py

@@ -564,3 +564,94 @@ class TestLegacyRunArun:
         assert isinstance(out, str)
         assert "denied" in out.lower()
         assert calls == []
+
+
+class TestStreamRegating:
+    """stream()/astream() gate at open and re-validate periodically so a
+    mid-stream policy revocation cuts the stream off."""
+
+    class _FlippingGuard:
+        """Allows the first N checks, denies afterwards."""
+
+        def __init__(self, allow_first: int):
+            self.allow_first = allow_first
+            self.calls = 0
+
+        def check(self, scope, **params):
+            from agentguard import CheckResult, DECISION_ALLOW, DECISION_DENY
+            self.calls += 1
+            if self.calls <= self.allow_first:
+                return CheckResult(decision=DECISION_ALLOW, reason="ok")
+            return CheckResult(decision=DECISION_DENY, reason="revoked mid-stream")
+
+    class _StreamingTool:
+        name = "streaming_tool"
+        description = "yields three chunks"
+
+        def stream(self, input, config=None, **kwargs):  # noqa: A002
+            yield "chunk-1"
+            yield "chunk-2"
+            yield "chunk-3"
+
+        async def astream(self, input, config=None, **kwargs):  # noqa: A002
+            for c in ("chunk-1", "chunk-2", "chunk-3"):
+                yield c
+
+        def _run(self, *a, **k):
+            return "done"
+
+    def test_stream_cut_off_on_mid_stream_revocation(self, monkeypatch):
+        from agentguard.adapters import langchain as lc_mod
+        from agentguard.adapters.langchain import GuardedTool
+
+        # Re-validate on every chunk so the revocation lands deterministically.
+        monkeypatch.setattr(lc_mod, "STREAM_REGATE_SECONDS", 0.0)
+
+        guard = self._FlippingGuard(allow_first=1)  # open-gate passes, first re-check denies
+        gt = GuardedTool(self._StreamingTool(), guard, scope="shell")
+
+        it = gt.stream("run")
+        with pytest.raises(PermissionError, match="revoked mid-stream"):
+            list(it)
+        assert guard.calls >= 2  # open gate + at least one re-check
+
+    def test_stream_completes_when_policy_stays_allowed(self, monkeypatch):
+        from agentguard.adapters import langchain as lc_mod
+        from agentguard.adapters.langchain import GuardedTool
+
+        monkeypatch.setattr(lc_mod, "STREAM_REGATE_SECONDS", 0.0)
+        guard = self._FlippingGuard(allow_first=10**9)
+        gt = GuardedTool(self._StreamingTool(), guard, scope="shell")
+
+        assert list(gt.stream("run")) == ["chunk-1", "chunk-2", "chunk-3"]
+        assert guard.calls >= 4  # open gate + one re-check per chunk
+
+    def test_astream_cut_off_on_mid_stream_revocation(self, monkeypatch):
+        import asyncio
+
+        from agentguard.adapters import langchain as lc_mod
+        from agentguard.adapters.langchain import GuardedTool
+
+        monkeypatch.setattr(lc_mod, "STREAM_REGATE_SECONDS", 0.0)
+        guard = self._FlippingGuard(allow_first=1)
+        gt = GuardedTool(self._StreamingTool(), guard, scope="shell")
+
+        async def consume():
+            chunks = []
+            async for c in gt.astream("run"):
+                chunks.append(c)
+            return chunks
+
+        with pytest.raises(PermissionError, match="revoked mid-stream"):
+            asyncio.run(consume())
+
+    def test_default_interval_does_not_recheck_fast_streams(self):
+        from agentguard.adapters.langchain import GuardedTool
+
+        guard = self._FlippingGuard(allow_first=1)  # any re-check would deny
+        gt = GuardedTool(self._StreamingTool(), guard, scope="shell")
+
+        # With the default 10s interval a sub-second stream never re-gates,
+        # so the hot path costs exactly one check.
+        assert list(gt.stream("run")) == ["chunk-1", "chunk-2", "chunk-3"]
+        assert guard.calls == 1