jev-firewall 0.1.0__py3-none-any.whl

jev_firewall/__init__.py

@@ -0,0 +1,48 @@
+"""jev-firewall: a runtime action firewall for AI agents, powered by TypeSafe's Jev."""
+
+from __future__ import annotations
+
+from jev_firewall.approval import (
+    ApprovalChannel,
+    ApprovalRequest,
+    ApprovalResult,
+    CLIApproval,
+    TimeoutDenyApproval,
+    WebhookApproval,
+)
+from jev_firewall.audit import AuditLog, read_audit
+from jev_firewall.engine import PolicyEngine
+from jev_firewall.errors import ActionBlocked, FirewallError, JevUnavailable, PolicyConfigError
+from jev_firewall.guard import Firewall
+from jev_firewall.jev import FakeJevClient, JevClient, build_jev_client
+from jev_firewall.policy import Policy, RiskThresholds
+from jev_firewall.verdict import Decision, JevAssessment, SeverityTier, ToolCall, Verdict
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ActionBlocked",
+    "ApprovalChannel",
+    "ApprovalRequest",
+    "ApprovalResult",
+    "AuditLog",
+    "CLIApproval",
+    "Decision",
+    "FakeJevClient",
+    "Firewall",
+    "FirewallError",
+    "JevAssessment",
+    "JevClient",
+    "JevUnavailable",
+    "Policy",
+    "PolicyConfigError",
+    "PolicyEngine",
+    "RiskThresholds",
+    "SeverityTier",
+    "TimeoutDenyApproval",
+    "ToolCall",
+    "Verdict",
+    "WebhookApproval",
+    "build_jev_client",
+    "read_audit",
+]

jev_firewall/_runtime.py

@@ -0,0 +1,75 @@
+"""Event-loop plumbing so one engine serves sync and async frameworks alike.
+
+Jev calls always run on a single background loop owned by the engine. HTTP connection pools
+are bound to the loop that created them, and agent frameworks call tools from a mix of
+threads, executor pools, and their own loops; pinning the client to one loop avoids
+"attached to a different loop" failures and keeps connections warm across calls.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import threading
+from collections.abc import Coroutine
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+class LoopThread:
+    def __init__(self, name: str = "jev-firewall-loop") -> None:
+        self._name = name
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread: threading.Thread | None = None
+        self._lock = threading.Lock()
+
+    def _ensure(self) -> asyncio.AbstractEventLoop:
+        with self._lock:
+            if self._loop is None or self._loop.is_closed():
+                loop = asyncio.new_event_loop()
+                ready = threading.Event()
+
+                def run() -> None:
+                    asyncio.set_event_loop(loop)
+                    loop.call_soon(ready.set)
+                    loop.run_forever()
+
+                self._thread = threading.Thread(target=run, name=self._name, daemon=True)
+                self._thread.start()
+                ready.wait()
+                self._loop = loop
+            return self._loop
+
+    def run(self, coro: Coroutine[Any, Any, T]) -> T:
+        """Run `coro` on the background loop and block the calling thread for the result."""
+        return asyncio.run_coroutine_threadsafe(coro, self._ensure()).result()
+
+    async def arun(self, coro: Coroutine[Any, Any, T]) -> T:
+        """Run `coro` on the background loop and await it from the caller's loop."""
+        return await asyncio.wrap_future(asyncio.run_coroutine_threadsafe(coro, self._ensure()))
+
+    def close(self) -> None:
+        with self._lock:
+            loop, self._loop = self._loop, None
+        if loop is not None and not loop.is_closed():
+            loop.call_soon_threadsafe(loop.stop)
+            if self._thread is not None:
+                self._thread.join(timeout=2)
+            loop.close()
+
+
+def run_sync(coro: Coroutine[Any, Any, T]) -> T:
+    """Run a coroutine to completion from sync code, in the caller's context.
+
+    Unlike `LoopThread.run`, this preserves the caller's contextvars (LangGraph's `interrupt()`
+    depends on them). Works even if the calling thread already has a running loop.
+    """
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(coro)
+    ctx = contextvars.copy_context()
+    with ThreadPoolExecutor(max_workers=1) as pool:
+        return pool.submit(ctx.run, asyncio.run, coro).result()

jev_firewall/adapters/__init__.py

@@ -0,0 +1 @@
+"""Thin framework adapters. Each imports its framework lazily; the core never imports them."""

jev_firewall/adapters/_common.py

@@ -0,0 +1,40 @@
+"""Framework-free helpers shared by adapters (never imported by the core package)."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+from typing import Any
+
+
+def first_user_text(messages: Iterable[Any] | None) -> str | None:
+    """Text of the first user/human message in a list of message objects or dicts.
+
+    Used as the default `agent_goal`. Only the user's own words count; tool output and
+    retrieved content come later in the conversation and cannot rewrite the goal.
+    """
+    for m in messages or ():
+        if isinstance(m, Mapping):
+            role = m.get("role") or m.get("type")
+            content = m.get("content")
+        else:
+            role = getattr(m, "role", None) or getattr(m, "type", None)
+            content = getattr(m, "content", None)
+        if role in ("human", "user"):
+            return content_text(content)
+    return None
+
+
+def content_text(content: Any) -> str | None:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, Sequence):
+        parts = []
+        for p in content:
+            if isinstance(p, Mapping):
+                parts.append(str(p.get("text") or ""))
+            elif isinstance(p, str):
+                parts.append(p)
+            else:
+                parts.append(str(getattr(p, "text", "") or ""))
+        return " ".join(x for x in parts if x) or None
+    return None

jev_firewall/adapters/google_adk.py

@@ -0,0 +1,126 @@
+"""Google ADK adapter: `before_tool_callback` for one agent, or a plugin for a whole Runner.
+
+Per agent:
+
+    fw_cb = JevFirewallCallbacks(firewall)
+    agent = LlmAgent(..., before_tool_callback=fw_cb.before_tool_callback,
+                     after_tool_callback=fw_cb.after_tool_callback)
+
+Every agent in an app:
+
+    app = App(name="ops", root_agent=root_agent, plugins=[JevFirewallPlugin(firewall)])
+    runner = InMemoryRunner(app=app)
+
+On a block, `on_block="result"` skips the tool and returns `{"error": ..., "jev_firewall":
+{...}}` to the model as the tool result (ADK's idiomatic veto). `on_block="raise"` raises
+`ActionBlocked`: from agent-level callbacks it propagates as is; ADK's plugin manager wraps
+plugin exceptions in `RuntimeError`, so from the plugin it arrives as that error's
+`__cause__`. Defaults: callbacks raise, the plugin returns a result.
+
+Requires `pip install jev-firewall[google_adk]`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Literal
+
+try:
+    from google.adk.plugins.base_plugin import BasePlugin
+    from google.adk.tools.base_tool import BaseTool
+    from google.adk.tools.tool_context import ToolContext
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        "jev_firewall.adapters.google_adk needs its framework: pip install 'jev-firewall[google_adk]'"
+    ) from exc
+
+from jev_firewall.adapters._common import content_text
+from jev_firewall.errors import ActionBlocked
+from jev_firewall.guard import Firewall
+from jev_firewall.verdict import ToolCall
+
+FRAMEWORK = "google_adk"
+
+AdkGoal = str | Callable[[ToolContext], str | None] | None
+
+
+def user_content_goal(tool_context: ToolContext) -> str | None:
+    """Default `agent_goal`: the user message that started this invocation."""
+    content = tool_context.user_content
+    if content is None or not content.parts:
+        return None
+    return content_text([p.text for p in content.parts if p.text])
+
+
+class JevFirewallCallbacks:
+    def __init__(
+        self,
+        firewall: Firewall,
+        *,
+        goal: AdkGoal = user_content_goal,
+        on_block: Literal["raise", "result"] = "raise",
+    ) -> None:
+        self.firewall = firewall
+        self.goal = goal
+        self.on_block = on_block
+
+    def _call(self, tool: BaseTool, args: dict[str, Any], ctx: ToolContext) -> ToolCall:
+        extra: dict[str, Any] = {}
+        if ctx.function_call_id:
+            extra["call_id"] = ctx.function_call_id
+        goal = self.goal(ctx) if callable(self.goal) else self.goal
+        return ToolCall(tool.name, dict(args), goal, framework=FRAMEWORK, **extra)
+
+    async def before_tool_callback(
+        self, tool: BaseTool, args: dict[str, Any], tool_context: ToolContext
+    ) -> dict[str, Any] | None:
+        try:
+            await self.firewall.acheck(self._call(tool, args, tool_context))
+        except ActionBlocked as exc:
+            if self.on_block == "raise":
+                raise
+            return {
+                "error": f"Action blocked by jev-firewall: {exc}",
+                "jev_firewall": {
+                    "decision": exc.verdict.decision.value,
+                    "reasons": list(exc.verdict.reasons),
+                },
+            }
+        return None  # only None lets ADK run the tool
+
+    async def after_tool_callback(
+        self, tool: BaseTool, args: dict[str, Any], tool_context: ToolContext, tool_response: Any
+    ) -> dict[str, Any] | None:
+        if tool_context.function_call_id:
+            self.firewall.record_outcome(tool_context.function_call_id, "executed")
+        return None
+
+
+class JevFirewallPlugin(BasePlugin):
+    """Runner-wide plugin. Plugin callbacks run before agent-level tool callbacks."""
+
+    def __init__(
+        self,
+        firewall: Firewall,
+        *,
+        goal: AdkGoal = user_content_goal,
+        on_block: Literal["raise", "result"] = "result",
+        name: str = "jev_firewall",
+    ) -> None:
+        super().__init__(name=name)
+        self._cb = JevFirewallCallbacks(firewall, goal=goal, on_block=on_block)
+
+    async def before_tool_callback(
+        self, *, tool: BaseTool, tool_args: dict[str, Any], tool_context: ToolContext
+    ) -> dict[str, Any] | None:
+        return await self._cb.before_tool_callback(tool, tool_args, tool_context)
+
+    async def after_tool_callback(
+        self,
+        *,
+        tool: BaseTool,
+        tool_args: dict[str, Any],
+        tool_context: ToolContext,
+        result: dict[str, Any],
+    ) -> dict[str, Any] | None:
+        return await self._cb.after_tool_callback(tool, tool_args, tool_context, result)

jev_firewall/adapters/langchain.py

@@ -0,0 +1,137 @@
+"""LangChain adapter.
+
+Two hooks, same core:
+
+`JevFirewallCallbackHandler` works with any LangChain tool invocation (LCEL chains, legacy
+agents, `tool.invoke`). It runs in `on_tool_start` and raises `ActionBlocked` before the
+tool body executes:
+
+    handler = JevFirewallCallbackHandler(firewall, goal="Summarize the Q3 report")
+    tool.invoke(args, config={"callbacks": [handler]})
+    # or pass the goal per run: config={"callbacks": [handler], "metadata": {"agent_goal": "..."}}
+
+`JevFirewallMiddleware` plugs into `langchain.agents.create_agent` (LangChain 1.x):
+
+    agent = create_agent(model, tools, middleware=[JevFirewallMiddleware(firewall)])
+
+Requires `pip install jev-firewall[langchain]`.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Awaitable, Callable, Mapping
+from typing import Any, Literal
+from uuid import UUID
+
+try:
+    from langchain_core.callbacks import BaseCallbackHandler
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        "jev_firewall.adapters.langchain needs its framework: pip install 'jev-firewall[langchain]'"
+    ) from exc
+
+from jev_firewall.guard import Firewall
+from jev_firewall.verdict import ToolCall
+
+FRAMEWORK = "langchain"
+
+CallbackGoal = str | Callable[[Mapping[str, Any]], str | None] | None
+
+
+class JevFirewallCallbackHandler(BaseCallbackHandler):
+    """Vetoes tool calls from `on_tool_start`.
+
+    This is a *sync* handler on purpose: LangChain swallows exceptions from async handlers on
+    the sync tool path, so an async handler could not block anything there. Sync handlers run
+    on both paths and `raise_error = True` makes their exceptions abort the tool.
+    """
+
+    raise_error: bool = True
+
+    def __init__(self, firewall: Firewall, *, goal: CallbackGoal = None) -> None:
+        super().__init__()
+        self.firewall = firewall
+        self.goal = goal
+        self._runs: dict[UUID, str] = {}
+        self._lock = threading.Lock()
+
+    def _goal(self, metadata: Mapping[str, Any]) -> str | None:
+        if callable(self.goal):
+            return self.goal(metadata)
+        if self.goal is not None:
+            return self.goal
+        g = metadata.get("agent_goal")
+        return None if g is None else str(g)
+
+    def on_tool_start(
+        self,
+        serialized: dict[str, Any],
+        input_str: str,
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        tags: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        inputs: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        name = str(serialized.get("name") or kwargs.get("name") or "unknown_tool")
+        args: dict[str, Any] = dict(inputs) if inputs is not None else {"input": input_str}
+        extra: dict[str, Any] = {}
+        if kwargs.get("tool_call_id"):
+            extra["call_id"] = str(kwargs["tool_call_id"])
+        call = ToolCall(name, args, self._goal(metadata or {}), framework=FRAMEWORK, **extra)
+        self.firewall.check(call)  # raises ActionBlocked on DENY or a rejected HOLD
+        with self._lock:
+            self._runs[run_id] = call.call_id
+
+    def on_tool_end(self, output: Any, *, run_id: UUID, **kwargs: Any) -> None:
+        with self._lock:
+            call_id = self._runs.pop(run_id, None)
+        if call_id is not None:
+            self.firewall.record_outcome(call_id, "executed")
+
+    def on_tool_error(self, error: BaseException, *, run_id: UUID, **kwargs: Any) -> None:
+        with self._lock:
+            call_id = self._runs.pop(run_id, None)
+        if call_id is not None:
+            self.firewall.record_outcome(call_id, "error", f"{type(error).__name__}: {error}")
+
+
+try:
+    from langchain.agents.middleware import AgentMiddleware
+    from langchain.tools.tool_node import ToolCallRequest
+    from langchain_core.messages import ToolMessage
+    from langgraph.types import Command
+except ImportError:  # pragma: no cover - only `langchain-core` installed
+    pass
+else:
+    from jev_firewall.adapters.langgraph import GoalSource, JevToolCallWrapper, first_human_message
+
+    class JevFirewallMiddleware(AgentMiddleware):
+        """`create_agent` middleware; the same interception as the LangGraph adapter."""
+
+        def __init__(
+            self,
+            firewall: Firewall,
+            *,
+            goal: GoalSource = first_human_message,
+            on_block: Literal["raise", "message"] = "message",
+        ) -> None:
+            super().__init__()
+            self._wrapper = JevToolCallWrapper(firewall, goal=goal, on_block=on_block)
+
+        def wrap_tool_call(
+            self,
+            request: ToolCallRequest,
+            handler: Callable[[ToolCallRequest], ToolMessage | Command[Any]],
+        ) -> ToolMessage | Command[Any]:
+            return self._wrapper(request, handler)
+
+        async def awrap_tool_call(
+            self,
+            request: ToolCallRequest,
+            handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command[Any]]],
+        ) -> ToolMessage | Command[Any]:
+            return await self._wrapper.acall(request, handler)

jev_firewall/adapters/langgraph.py

@@ -0,0 +1,161 @@
+"""LangGraph adapter: intercept tool calls in `ToolNode` via `wrap_tool_call`.
+
+    from jev_firewall import Firewall
+    from jev_firewall.adapters.langgraph import firewall_tool_node
+
+    firewall = Firewall.from_yaml("policy.yaml")
+    tools_node = firewall_tool_node([terminal, send_email], firewall)
+    builder.add_node("tools", tools_node)
+
+HOLD is resolved by the firewall's approval channel. To pause the graph instead (needs a
+checkpointer), pass `LangGraphInterruptApproval()` as the Firewall's approval channel and
+resume with `Command(resume={"approved": True, "resolver": "alice"})`.
+
+Requires `pip install jev-firewall[langgraph]`.
+"""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from typing import Any, Literal
+
+try:
+    from langchain_core.messages import ToolMessage
+    from langchain_core.tools import BaseTool
+    from langgraph.prebuilt import ToolNode
+    from langgraph.prebuilt.tool_node import ToolCallRequest
+    from langgraph.types import Command, interrupt
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        "jev_firewall.adapters.langgraph needs its framework: pip install 'jev-firewall[langgraph]'"
+    ) from exc
+
+from jev_firewall.adapters._common import first_user_text
+from jev_firewall.approval import ApprovalRequest, ApprovalResult
+from jev_firewall.errors import ActionBlocked
+from jev_firewall.guard import Firewall
+from jev_firewall.verdict import Decision, ToolCall, Verdict
+
+GoalSource = str | Callable[[Any], str | None] | None
+ToolResult = ToolMessage | Command[Any]
+
+FRAMEWORK = "langgraph"
+
+
+def first_human_message(state: Any) -> str | None:
+    """Default `agent_goal`: the first human message in `state["messages"]`."""
+    messages = state.get("messages") if isinstance(state, Mapping) else getattr(state, "messages", None)
+    return first_user_text(messages)
+
+
+class JevToolCallWrapper:
+    """A `wrap_tool_call` / `awrap_tool_call` pair for `ToolNode` (or any compatible hook).
+
+    `on_block="raise"` lets `ActionBlocked` propagate and stops the run.
+    `on_block="message"` returns an error `ToolMessage` instead so the model can recover.
+    """
+
+    def __init__(
+        self,
+        firewall: Firewall,
+        *,
+        goal: GoalSource = first_human_message,
+        on_block: Literal["raise", "message"] = "raise",
+        cache_size: int = 1024,
+    ) -> None:
+        self.firewall = firewall
+        self.goal = goal
+        self.on_block = on_block
+        # Verdicts for held calls, keyed by tool_call id. A LangGraph interrupt re-runs the node
+        # on resume; reusing the verdict avoids a second Jev call and a second audit record.
+        self._held: OrderedDict[str, Verdict] = OrderedDict()
+        self._cache_size = cache_size
+
+    def _call(self, request: ToolCallRequest) -> ToolCall:
+        tc = request.tool_call
+        goal = self.goal(request.state) if callable(self.goal) else self.goal
+        kwargs: dict[str, Any] = {}
+        if tc.get("id"):
+            kwargs["call_id"] = str(tc["id"])
+        return ToolCall(tc["name"], dict(tc.get("args") or {}), goal, framework=FRAMEWORK, **kwargs)
+
+    def _remember(self, v: Verdict) -> None:
+        if v.decision is Decision.HOLD:
+            self._held[v.call_id] = v
+            while len(self._held) > self._cache_size:
+                self._held.popitem(last=False)
+
+    def _blocked(self, request: ToolCallRequest, exc: ActionBlocked) -> ToolMessage:
+        if self.on_block == "raise":
+            raise exc
+        return ToolMessage(
+            content=f"Action blocked by jev-firewall: {exc}",
+            name=request.tool_call["name"],
+            tool_call_id=request.tool_call["id"] or "",
+            status="error",
+        )
+
+    def __call__(
+        self, request: ToolCallRequest, execute: Callable[[ToolCallRequest], ToolResult]
+    ) -> ToolResult:
+        call = self._call(request)
+        verdict = self._held.get(call.call_id) or self.firewall.engine.evaluate(call)
+        self._remember(verdict)
+        try:
+            self.firewall.resolve(verdict)
+        except ActionBlocked as exc:
+            self._held.pop(call.call_id, None)
+            return self._blocked(request, exc)
+        self._held.pop(call.call_id, None)
+        return self.firewall.guard_executed(call, lambda: execute(request))
+
+    async def acall(
+        self, request: ToolCallRequest, execute: Callable[[ToolCallRequest], Awaitable[ToolResult]]
+    ) -> ToolResult:
+        call = self._call(request)
+        verdict = self._held.get(call.call_id) or await self.firewall.engine.aevaluate(call)
+        self._remember(verdict)
+        try:
+            await self.firewall.aresolve(verdict)
+        except ActionBlocked as exc:
+            self._held.pop(call.call_id, None)
+            return self._blocked(request, exc)
+        self._held.pop(call.call_id, None)
+        return await self.firewall.aguard_executed(call, lambda: execute(request))
+
+
+def firewall_tool_node(
+    tools: Sequence[BaseTool | Callable[..., Any]],
+    firewall: Firewall,
+    *,
+    goal: GoalSource = first_human_message,
+    on_block: Literal["raise", "message"] = "raise",
+    **tool_node_kwargs: Any,
+) -> ToolNode:
+    """A `ToolNode` whose every tool call goes through the firewall first."""
+    wrapper = JevToolCallWrapper(firewall, goal=goal, on_block=on_block)
+    return ToolNode(tools, wrap_tool_call=wrapper, awrap_tool_call=wrapper.acall, **tool_node_kwargs)
+
+
+class LangGraphInterruptApproval:
+    """Approval channel that pauses the graph with `interrupt()` (requires a checkpointer).
+
+    The interrupt value is `{"type": "jev_firewall_hold", ...ApprovalRequest}`. Resume with
+    `Command(resume=True)`, `Command(resume="yes")` or
+    `Command(resume={"approved": True, "resolver": "alice", "note": "..."})`.
+    """
+
+    async def request(self, req: ApprovalRequest) -> ApprovalResult:
+        answer = interrupt({"type": "jev_firewall_hold", **req.to_dict()})
+        if isinstance(answer, Mapping):
+            return ApprovalResult(
+                approved=answer.get("approved") is True,
+                resolver=str(answer.get("resolver") or "langgraph:resume"),
+                note=None if answer.get("note") is None else str(answer["note"]),
+            )
+        if isinstance(answer, str):
+            return ApprovalResult(
+                answer.strip().lower() in {"y", "yes", "approve", "approved"}, "langgraph:resume"
+            )
+        return ApprovalResult(answer is True, "langgraph:resume")