firstops 0.2.0__py3-none-any.whl

firstops/events.py

@@ -0,0 +1,195 @@
+"""Action-event model and wire (de)serialization for hook evaluation.
+
+Mirrors the backend ``hookwire`` JSON contract exactly (see
+``backend/shared/lib/hookwire/types.go``):
+
+  request : event_type, agent, tool_name, tool_input(obj), tool_output(obj),
+            session_id, cwd, channel, mcp{server,tool,url}, cli_version
+  response: decision, reason, modified_payload(base64 bytes), policy_id
+
+Principal and tenant are resolved server-side from the DPoP JWK thumbprint and
+are never sent in the body.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+from dataclasses import dataclass
+from typing import Any
+
+# --- channel constants (match enforcement/types.go Channel) ---
+CHANNEL_MCP = "mcp"
+CHANNEL_SYSTEM_TOOLS = "system_tools"
+CHANNEL_LLM = "llm"
+
+# --- event types (match enforcement EventType) ---
+EVENT_PRE_TOOL_USE = "pre_tool_use"
+EVENT_POST_TOOL_USE = "post_tool_use"
+
+# --- decisions (match hookwire response decision) ---
+DECISION_ALLOW = "allow"
+DECISION_DENY = "deny"
+DECISION_ASK = "ask"
+DECISION_MODIFY = "modify"
+_KNOWN_DECISIONS = frozenset(
+    {DECISION_ALLOW, DECISION_DENY, DECISION_ASK, DECISION_MODIFY}
+)
+
+# Producer label for the `agent` field. The backend normalizer
+# (FromHookRequest) maps this to audit Source `SourceSDK` ("sdk") per
+# design-doc §7, so SDK actions are attributed correctly in audit. Keep this
+# value in sync with the normalizer's `req.Agent == "firstops-sdk"` case.
+SDK_AGENT_LABEL = "firstops-sdk"
+
+
+@dataclass
+class MCPInfo:
+    """MCP-specific metadata; populated only when ``channel == "mcp"``."""
+
+    server: str = ""
+    tool: str = ""
+    url: str = ""
+
+    def to_wire(self) -> dict[str, str]:
+        out: dict[str, str] = {}
+        if self.server:
+            out["server"] = self.server
+        if self.tool:
+            out["tool"] = self.tool
+        if self.url:
+            out["url"] = self.url
+        return out
+
+
+@dataclass
+class ActionEvent:
+    """A single governable action, serializable to the hookwire request shape."""
+
+    event_type: str
+    tool_name: str
+    channel: str = ""
+    tool_input: dict[str, Any] | None = None
+    tool_output: dict[str, Any] | None = None
+    agent: str = SDK_AGENT_LABEL
+    session_id: str = ""
+    cwd: str = ""
+    mcp: MCPInfo | None = None
+    cli_version: str = ""
+    # The producer can apply a request-path modification before the action runs
+    # (decorator rebind / Claude updatedInput / LangGraph arg rewrite / LLM body
+    # rewrite). When True, sentinel ships `modify` for outbound scrub instead of
+    # escalating to deny. Adapters that CAN'T mutate (OpenAI guardrails) leave
+    # this False.
+    producer_can_apply_modify: bool = False
+    # Free-form producer metadata (e.g. {"harness": "langgraph"}). Merged into
+    # the event metadata server-side and surfaced in audit.
+    metadata: dict[str, str] | None = None
+
+    def to_wire(self) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "event_type": self.event_type,
+            "agent": self.agent,
+            "tool_name": self.tool_name,
+        }
+        # tool_input/output are JSON objects (not stringified) so nested
+        # structure is preserved end-to-end.
+        if self.tool_input is not None:
+            body["tool_input"] = self.tool_input
+        if self.tool_output is not None:
+            body["tool_output"] = self.tool_output
+        if self.session_id:
+            body["session_id"] = self.session_id
+        if self.cwd:
+            body["cwd"] = self.cwd
+        if self.channel:
+            body["channel"] = self.channel
+        if self.mcp is not None:
+            mcp_wire = self.mcp.to_wire()
+            if mcp_wire:
+                body["mcp"] = mcp_wire
+        if self.cli_version:
+            body["cli_version"] = self.cli_version
+        if self.producer_can_apply_modify:
+            body["producer_can_apply_modify"] = True
+        if self.metadata:
+            body["metadata"] = self.metadata
+        return body
+
+
+@dataclass
+class Decision:
+    """The enforcement verdict for an action."""
+
+    action: str = DECISION_ALLOW
+    reason: str = ""
+    modified_payload: bytes | None = None
+    policy_id: str = ""
+    failed_open: bool = False  # True when we allowed due to an infra failure
+
+    @property
+    def blocked(self) -> bool:
+        return self.action == DECISION_DENY
+
+    @property
+    def modified(self) -> bool:
+        return self.action == DECISION_MODIFY and self.modified_payload is not None
+
+    @classmethod
+    def from_wire(cls, data: dict[str, Any]) -> Decision:
+        action = data.get("decision") or DECISION_ALLOW
+        reason = data.get("reason", "") or ""
+        policy_id = data.get("policy_id", "") or ""
+
+        # An unrecognized verdict must not silently behave like a clean allow:
+        # fail open (never block on a verdict we can't act on) but set the
+        # failed_open flag so it is visible downstream, not indistinguishable
+        # from a real allow.
+        if action not in _KNOWN_DECISIONS:
+            return cls(
+                action=DECISION_ALLOW,
+                reason=f"unknown decision {action!r}: {reason}".rstrip(": "),
+                policy_id=policy_id,
+                failed_open=True,
+            )
+
+        raw = data.get("modified_payload")
+        payload: bytes | None = None
+        if raw:
+            try:
+                # Go marshals []byte as a base64 string. validate=True so a
+                # corrupted payload raises instead of silently decoding to
+                # wrong bytes that would then be applied to a live call.
+                payload = (
+                    base64.b64decode(raw, validate=True)
+                    if isinstance(raw, str)
+                    else bytes(raw)
+                )
+            except (binascii.Error, ValueError):
+                return cls(
+                    action=DECISION_ALLOW,
+                    reason=f"invalid modified_payload: {reason}".rstrip(": "),
+                    policy_id=policy_id,
+                    failed_open=True,
+                )
+
+        # A modify verdict with no usable payload is malformed: fail open
+        # visibly rather than report a "modify" the caller can't apply.
+        if action == DECISION_MODIFY and payload is None:
+            return cls(
+                action=DECISION_ALLOW,
+                reason=f"modify without payload: {reason}".rstrip(": "),
+                policy_id=policy_id,
+                failed_open=True,
+            )
+
+        return cls(
+            action=action,
+            reason=reason,
+            modified_payload=payload,
+            policy_id=policy_id,
+        )
+
+    @classmethod
+    def fail_open(cls, reason: str) -> Decision:
+        return cls(action=DECISION_ALLOW, reason=reason, failed_open=True)

firstops/integrations/__init__.py

@@ -0,0 +1,12 @@
+"""Harness adapters — one-touch governance for supported agent frameworks.
+
+Each adapter wires the FirstOps enforcement spine into a framework's official,
+intervention-capable extension point:
+
+  - ``firstops.integrations.claude``        — Claude Agent SDK ``PreToolUse`` hook
+  - ``firstops.integrations.langgraph``     — LangGraph agent middleware (wrap_tool_call)
+  - ``firstops.integrations.openai_agents`` — OpenAI Agents SDK tool guardrails
+
+Adapters import their framework lazily, so importing this package never
+requires the frameworks to be installed.
+"""

firstops/integrations/_common.py

@@ -0,0 +1,132 @@
+"""Shared governance core for harness adapters.
+
+The adapters all reduce to: build a pre_tool_use event, ask sentinel, translate
+the Decision into the framework's native verb (deny / mutate / allow). That
+reduction lives here so every adapter shares one tested implementation.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from firstops.channels import classify, mcp_info
+from firstops.events import CHANNEL_MCP, EVENT_PRE_TOOL_USE, ActionEvent, Decision
+
+# A neutral decision vocabulary the adapters translate into framework types.
+ACTION_ALLOW = "allow"
+ACTION_DENY = "deny"
+ACTION_MODIFY = "modify"
+
+# Harness identifiers stamped into event metadata (audit/filtering).
+HARNESS_LANGGRAPH = "langgraph"
+HARNESS_CLAUDE = "claude-agent-sdk"
+HARNESS_OPENAI_AGENTS = "openai-agents"
+
+
+def _json_safe(value: Any) -> Any:
+    """Return a JSON-serializable view of ``value`` (str fallback)."""
+    try:
+        json.dumps(value)
+        return value
+    except (TypeError, ValueError):
+        return str(value)
+
+
+def coerce_input(tool_input: Any) -> dict[str, Any]:
+    """Normalize a framework's tool input into a JSON-able dict for the event.
+
+    Never raises and always returns a JSON-serializable dict (bytes decode with
+    ``errors="replace"``; non-serializable objects are stringified) so a tool
+    passing binary/exotic args can't crash the agent loop.
+    """
+    if isinstance(tool_input, dict):
+        return {k: _json_safe(v) for k, v in tool_input.items()}
+    if isinstance(tool_input, bytes):
+        tool_input = tool_input.decode("utf-8", errors="replace")
+    if isinstance(tool_input, str):
+        try:
+            parsed = json.loads(tool_input)
+            if isinstance(parsed, dict):
+                return {k: _json_safe(v) for k, v in parsed.items()}
+        except (ValueError, TypeError):
+            pass
+        return {"input": tool_input}
+    if tool_input is None:
+        return {}
+    return {"input": _json_safe(tool_input)}
+
+
+def govern_tool(
+    rt,
+    tool_name: str,
+    tool_input: Any,
+    can_apply_modify: bool = False,
+    harness: str = "",
+) -> Decision:
+    """Evaluate a tool call via the enforcement spine. Allows if no runtime.
+
+    ``can_apply_modify``: True when the adapter can rewrite the tool args before
+    execution (Claude updatedInput, LangGraph arg rewrite) — lets sentinel ship
+    a request-path scrub as ``modify`` instead of escalating to deny. Adapters
+    that can't mutate (OpenAI guardrails) leave it False.
+
+    ``harness``: the producing framework, stamped into event metadata when known.
+
+    Hardened to never raise into the agent loop: a None/odd tool_name and
+    non-serializable inputs are coerced rather than propagated.
+    """
+    if rt is None:
+        return Decision(action="allow")
+    name = tool_name or ""
+    channel = classify(name)
+    event = ActionEvent(
+        event_type=EVENT_PRE_TOOL_USE,
+        tool_name=name,
+        channel=channel,
+        # coerce_input already returns a fresh dict — no aliasing of the
+        # caller's live args (which frameworks may mutate after the call).
+        tool_input=coerce_input(tool_input),
+        mcp=mcp_info(name) if channel == CHANNEL_MCP else None,
+        producer_can_apply_modify=can_apply_modify,
+        metadata={"harness": harness} if harness else None,
+    )
+    return rt.enforcement.evaluate(event)
+
+
+def modified_input(decision: Decision) -> dict[str, Any] | None:
+    """Return the scrubbed input dict from a modify decision, or None."""
+    if decision.modified and decision.modified_payload:
+        try:
+            value = json.loads(decision.modified_payload)
+            if isinstance(value, dict):
+                return value
+        except (ValueError, TypeError):
+            pass
+    return None
+
+
+def decide(
+    rt,
+    tool_name: str,
+    tool_input: Any,
+    can_apply_modify: bool = False,
+    harness: str = "",
+) -> tuple[str, Any]:
+    """Reduce a tool call to ``(action, payload)``:
+
+    - ``("deny", reason)`` — block the call
+    - ``("modify", new_input_dict)`` — proceed with scrubbed input
+    - ``("allow", None)`` — proceed unchanged
+
+    ``can_apply_modify`` and ``harness`` are forwarded to the event (see govern_tool).
+    """
+    decision = govern_tool(
+        rt, tool_name, tool_input, can_apply_modify=can_apply_modify, harness=harness
+    )
+    if decision.blocked:
+        return ACTION_DENY, decision.reason or "blocked by FirstOps policy"
+    new_input = modified_input(decision)
+    if new_input is not None:
+        return ACTION_MODIFY, new_input
+    return ACTION_ALLOW, None

firstops/integrations/claude.py

@@ -0,0 +1,84 @@
+"""Claude Agent SDK adapter — the daemon model, in-process.
+
+A single ``PreToolUse`` hook governs every tool the agent calls: built-ins
+(``Bash``, ``Write``, ``WebFetch``), MCP tools (``mcp__*``), and in-process
+SDK-MCP tools — with both block (deny) and argument rewrite (updatedInput).
+
+Usage::
+
+    from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
+    from firstops.integrations.claude import firstops_hooks
+
+    options = ClaudeAgentOptions(hooks=firstops_hooks(fo))
+    async with ClaudeSDKClient(options=options) as client:
+        ...
+
+Targets the Claude Agent SDK PreToolUse hook contract (hookSpecificOutput /
+permissionDecision). The governance logic (`_govern_pre_tool_use`) is
+framework-free and unit-tested; `firstops_hooks` is the thin lazily-imported
+shell.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from firstops import _runtime
+from firstops.integrations._common import (
+    ACTION_DENY,
+    ACTION_MODIFY,
+    HARNESS_CLAUDE,
+    decide,
+)
+
+
+def _govern_pre_tool_use(rt, input_data: dict[str, Any]) -> dict[str, Any]:
+    """Map a PreToolUse hook input to a hook response. Pure / testable.
+
+    Returns ``{}`` (allow) when there's nothing to do, a deny envelope, or an
+    allow-with-updatedInput envelope for a scrub.
+    """
+    tool_name = input_data.get("tool_name", "") or ""
+    tool_input = input_data.get("tool_input")
+    # Claude PreToolUse updatedInput can rewrite args → request-path scrub applies.
+    action, payload = decide(
+        rt, tool_name, tool_input, can_apply_modify=True, harness=HARNESS_CLAUDE
+    )
+    if action == ACTION_DENY:
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": payload,
+            }
+        }
+    # Only emit an updatedInput envelope when there's a non-empty replacement —
+    # Claude's updatedInput is a FULL replacement of tool_input, so an empty
+    # dict would wipe every argument. Empty/odd payload → allow unchanged.
+    if action == ACTION_MODIFY and isinstance(payload, dict) and payload:
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "allow",
+                "updatedInput": payload,
+            }
+        }
+    return {}
+
+
+def firstops_hooks(fo=None) -> dict[str, Any]:
+    """Return a Claude Agent SDK ``hooks`` config that governs all tool calls."""
+    rt = fo if fo is not None else _runtime.runtime()
+    try:
+        from claude_agent_sdk import HookMatcher
+    except ImportError as e:  # pragma: no cover - env-dependent
+        raise RuntimeError(
+            "claude-agent-sdk is not installed: pip install claude-agent-sdk"
+        ) from e
+
+    async def _pre_tool_use(input_data, tool_use_id, context):
+        return _govern_pre_tool_use(rt, input_data)
+
+    # matcher=None is the match-ALL contract; "*" would match only a tool
+    # literally named "*" (i.e. nothing) and silently disable governance.
+    return {"PreToolUse": [HookMatcher(matcher=None, hooks=[_pre_tool_use])]}

firstops/integrations/langgraph.py

@@ -0,0 +1,87 @@
+"""LangGraph adapter — agent middleware that governs every tool call.
+
+Built on LangChain v1 agent middleware (`wrap_tool_call`), which can block
+(return a ToolMessage instead of running the tool) and mutate (rewrite the
+tool args). One middleware governs all tools the agent calls, including
+framework built-ins (`ShellTool`, `SQLDatabaseToolkit`, …) the developer never
+authored.
+
+Usage::
+
+    from langchain.agents import create_agent
+    from firstops.integrations.langgraph import FirstOpsMiddleware
+
+    agent = create_agent(model, tools=[...], middleware=[FirstOpsMiddleware(fo)])
+
+Coverage honesty: middleware attaches per compiled graph and does NOT
+auto-propagate into subgraphs. A subgraph built without FirstOps middleware is
+ungoverned — wire one per graph. (Detect-and-warn for subgraphs is tracked for
+a later milestone.)
+
+The decision logic is `firstops.integrations._common.decide` (framework-free,
+tested); `FirstOpsMiddleware` is the thin lazily-imported shell targeting the
+LangChain v1 middleware API.
+"""
+
+from __future__ import annotations
+
+from firstops import _runtime
+from firstops.integrations._common import (
+    ACTION_DENY,
+    ACTION_MODIFY,
+    HARNESS_LANGGRAPH,
+    decide,
+)
+
+
+def FirstOpsMiddleware(fo=None):
+    """Return a LangChain agent middleware instance that governs tool calls."""
+    rt = fo if fo is not None else _runtime.runtime()
+    try:
+        from langchain.agents.middleware import AgentMiddleware
+        from langchain_core.messages import ToolMessage
+    except ImportError as e:  # pragma: no cover - env-dependent
+        raise RuntimeError(
+            "langchain/langgraph not installed: pip install langchain langgraph"
+        ) from e
+
+    class _FirstOpsMiddleware(AgentMiddleware):
+        def wrap_tool_call(self, request, handler):
+            call = getattr(request, "tool_call", None) or {}
+            name = call.get("name", "") or ""
+            args = call.get("args", {}) or {}
+            action, payload = decide(
+                rt, name, args, can_apply_modify=True, harness=HARNESS_LANGGRAPH
+            )
+            if action == ACTION_DENY:
+                return ToolMessage(
+                    content=f"blocked by FirstOps policy: {payload}",
+                    tool_call_id=call.get("id", ""),
+                    status="error",
+                )
+            if action == ACTION_MODIFY:
+                request = request.override(
+                    tool_call={**request.tool_call, "args": payload}
+                )
+            return handler(request)
+
+        async def awrap_tool_call(self, request, handler):
+            call = getattr(request, "tool_call", None) or {}
+            name = call.get("name", "") or ""
+            args = call.get("args", {}) or {}
+            action, payload = decide(
+                rt, name, args, can_apply_modify=True, harness=HARNESS_LANGGRAPH
+            )
+            if action == ACTION_DENY:
+                return ToolMessage(
+                    content=f"blocked by FirstOps policy: {payload}",
+                    tool_call_id=call.get("id", ""),
+                    status="error",
+                )
+            if action == ACTION_MODIFY:
+                request = request.override(
+                    tool_call={**request.tool_call, "args": payload}
+                )
+            return await handler(request)
+
+    return _FirstOpsMiddleware()

firstops/integrations/openai_agents.py

@@ -0,0 +1,87 @@
+"""OpenAI Agents SDK adapter — tool input guardrails.
+
+Uses the SDK's tool input guardrail to block a tool call before it runs.
+
+**Attachment is per-tool, not per-agent.** OpenAI Agents has no agent-level
+tool-input guardrail — `tool_input_guardrails` is a field on `@function_tool` /
+`FunctionTool`. So wire the FirstOps guardrail onto each function tool::
+
+    from agents import function_tool
+    from firstops.integrations.openai_agents import firstops_tool_input_guardrail
+
+    guard = firstops_tool_input_guardrail(fo)
+
+    @function_tool(tool_input_guardrails=[guard])
+    def send_email(to: str, body: str): ...
+
+Capability note (honest): OpenAI Agents tool guardrails are **read-only** — they
+can block but cannot mutate tool arguments. So argument *scrub* is not available
+through this adapter; a ``modify`` decision degrades to allow here. To scrub tool
+args on OpenAI Agents, wrap the underlying function with ``@firstops.tool``
+instead (the base-API decorator).
+
+The decision logic (`_decide_tool`) is framework-free and tested; the guardrail
+wiring is the thin lazily-imported shell.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from firstops import _runtime
+from firstops.integrations._common import (
+    ACTION_DENY,
+    ACTION_MODIFY,
+    HARNESS_OPENAI_AGENTS,
+    decide,
+)
+
+
+def _decide_tool(rt, tool_name: str, tool_input: Any) -> tuple[bool, str]:
+    """Return ``(blocked, reason)`` for a tool call.
+
+    Guardrails can't mutate args (read-only). We leave ``can_apply_modify``
+    False, so sentinel escalates a request-path scrub to deny — but defensively,
+    if a ``modify`` ever reaches here we **block** (fail closed) rather than let
+    unscrubbed arguments through. To scrub on OpenAI Agents, use ``@firstops.tool``.
+    """
+    action, payload = decide(rt, tool_name, tool_input, harness=HARNESS_OPENAI_AGENTS)
+    if action == ACTION_DENY:
+        return True, str(payload)
+    if action == ACTION_MODIFY:
+        return True, (
+            "scrub required but tool-arg rewrite is unsupported on OpenAI Agents "
+            "(use @firstops.tool to scrub)"
+        )
+    return False, ""
+
+
+def firstops_tool_input_guardrail(fo=None):
+    """Return a single reusable tool-input guardrail to attach per function tool.
+
+    Pass it in each tool's ``tool_input_guardrails=[...]`` list.
+    """
+    rt = fo if fo is not None else _runtime.runtime()
+    try:
+        from agents import tool_input_guardrail
+        from agents.tool_guardrails import ToolGuardrailFunctionOutput
+    except ImportError as e:  # pragma: no cover - env-dependent
+        raise RuntimeError(
+            "openai-agents not installed: pip install openai-agents"
+        ) from e
+
+    @tool_input_guardrail
+    async def _fo_tool_input_guardrail(data):
+        # ToolInputGuardrailData carries .context (ToolContext) and .agent.
+        # tool_arguments is a raw JSON string; coerce_input handles that.
+        ctx = getattr(data, "context", None)
+        tool_name = getattr(ctx, "tool_name", "") or ""
+        tool_args = getattr(ctx, "tool_arguments", None)
+        blocked, reason = _decide_tool(rt, tool_name, tool_args)
+        if blocked:
+            return ToolGuardrailFunctionOutput.reject_content(
+                message=f"blocked by FirstOps policy: {reason}"
+            )
+        return ToolGuardrailFunctionOutput.allow()
+
+    return _fo_tool_input_guardrail

firstops/llm.py

@@ -0,0 +1,51 @@
+"""Convenience helpers for pointing LLM clients at the sidecar chain-link.
+
+These are optional sugar over :func:`firstops.llm_base_url`. The SDK does not
+depend on ``openai`` / ``anthropic`` — the client factories import them lazily
+and raise a clear error if the package is absent.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from firstops._runtime import llm_base_url
+
+
+def openai_client(**kwargs: Any):
+    """Return an ``openai.OpenAI`` client pointed at the sidecar.
+
+    Pass your real ``api_key`` as usual (or set ``OPENAI_API_KEY``) — it is
+    forwarded verbatim to the upstream; FirstOps never stores it.
+    """
+    try:
+        import openai
+    except ImportError as e:  # pragma: no cover - env-dependent
+        raise RuntimeError("openai is not installed: pip install openai") from e
+    kwargs.setdefault("base_url", llm_base_url("openai"))
+    return openai.OpenAI(**kwargs)
+
+
+def anthropic_client(**kwargs: Any):
+    """Return an ``anthropic.Anthropic`` client pointed at the sidecar."""
+    try:
+        import anthropic
+    except ImportError as e:  # pragma: no cover - env-dependent
+        raise RuntimeError("anthropic is not installed: pip install anthropic") from e
+    kwargs.setdefault("base_url", llm_base_url("anthropic"))
+    return anthropic.Anthropic(**kwargs)
+
+
+def configure_llm_env() -> dict[str, str]:
+    """Set ``OPENAI_BASE_URL`` / ``ANTHROPIC_BASE_URL`` to the sidecar.
+
+    For frameworks that construct their own LLM client internally and only
+    honor the env vars. Returns the variables it set.
+    """
+    env = {
+        "OPENAI_BASE_URL": llm_base_url("openai"),
+        "ANTHROPIC_BASE_URL": llm_base_url("anthropic"),
+    }
+    os.environ.update(env)
+    return env