toolwall 0.2.0__py3-none-any.whl

toolwall/__init__.py

@@ -0,0 +1,56 @@
+"""toolwall: fail-closed firewall for AI agent tool calls.
+
+Structured outputs guarantee your agent's tool calls are well-formed.
+toolwall guarantees they're allowed.
+"""
+
+from toolwall.gate import Gate, GateResult, ToolRegistry, Verdict
+from toolwall.intake import IntakeError, ToolCall, parse_tool_calls
+from toolwall.meter import Meter, RunEvent, RunReport, extract_usage
+from toolwall.policy import (
+    Policy,
+    ends_with,
+    in_range,
+    matches,
+    max_len,
+    not_empty,
+    one_of,
+    starts_with,
+)
+from toolwall.schema import ToolSchema, schema_from_signature
+from toolwall.shield import Finding, Shield
+from toolwall.suggest import suggest_policies
+from toolwall.mcp_guard import GuardedCall, MCPGuard, to_mcp_error
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Gate",
+    "GateResult",
+    "Verdict",
+    "ToolRegistry",
+    "ToolCall",
+    "IntakeError",
+    "parse_tool_calls",
+    "Meter",
+    "RunEvent",
+    "RunReport",
+    "extract_usage",
+    "Policy",
+    "in_range",
+    "one_of",
+    "matches",
+    "max_len",
+    "ends_with",
+    "starts_with",
+    "not_empty",
+    "ToolSchema",
+    "schema_from_signature",
+    "Shield",
+    "Finding",
+    "suggest_policies",
+    "MCPGuard",
+    "GuardedCall",
+    "to_mcp_error",
+    "__version__",
+]

toolwall/cli.py

@@ -0,0 +1,44 @@
+"""toolwall CLI — inspect meter/audit exports."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def cmd_report(args: argparse.Namespace) -> int:
+    data = json.loads(Path(args.file).read_text(encoding="utf-8"))
+    summary = data.get("summary") or {}
+    print(f"Model:  {data.get('model', 'unknown')}")
+    print(f"Events: {summary.get('event_count', len(data.get('events', [])))}")
+    for lane, stats in (summary.get("lanes") or {}).items():
+        print(f"\n[{lane}]")
+        for key in (
+            "prompt_tokens",
+            "completion_tokens",
+            "total_tokens",
+            "estimated_cost_usd",
+            "intercept_success_rate",
+        ):
+            print(f"  {key}: {stats.get(key)}")
+    if summary.get("note"):
+        print(f"\nNote: {summary['note']}")
+    return 0
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(prog="toolwall", description="toolwall dev tools")
+    sub = ap.add_subparsers(dest="command", required=True)
+
+    report = sub.add_parser("report", help="Print summary from a Meter JSON export")
+    report.add_argument("file", help="Path to meter/audit JSON")
+    report.set_defaults(func=cmd_report)
+
+    args = ap.parse_args()
+    sys.exit(args.func(args))
+
+
+if __name__ == "__main__":
+    main()

toolwall/gate.py

@@ -0,0 +1,381 @@
+"""toolwall: fail-closed checkpoint between LLM tool calls and execution.
+
+    gate = Gate(default="deny", meter=meter, shield=Shield(mode="block"))
+    gate.register("db_query", db_query,
+                  schema=ToolSchema(required=["q"]),
+                  policy=Policy(constraints={"limit": in_range(1, 100)}))
+    gate.budget(max_calls=20)
+    result = gate.run(openai_response)   # check + execute only if allowed
+
+Check order (first failure blocks, fail-closed):
+  intake -> known tool -> budget -> schema -> policy -> shield -> approval
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Literal
+
+from toolwall.intake import IntakeError, ToolCall, parse_tool_calls
+from toolwall.meter import Meter, RunEvent
+from toolwall.policy import Policy
+from toolwall.schema import ToolSchema, schema_from_signature
+from toolwall.shield import Finding, Shield
+
+ToolFn = Callable[..., Any]
+DefaultMode = Literal["deny", "allow"]
+ApprovalHandler = Callable[["GateResult"], bool]
+
+
+class Verdict(str, Enum):
+    ALLOW = "allow"
+    BLOCK = "block"
+    NEEDS_APPROVAL = "needs_approval"
+
+
+@dataclass
+class ToolRegistry:
+    """Maps tool names to callables (+ optional schema and policy).
+
+    Registration is the allowlist: unregistered tools always block.
+    """
+
+    _tools: dict[str, ToolFn] = field(default_factory=dict)
+    _schemas: dict[str, ToolSchema] = field(default_factory=dict)
+    _policies: dict[str, Policy] = field(default_factory=dict)
+
+    def register(
+        self,
+        name: str,
+        fn: ToolFn,
+        schema: ToolSchema | None = None,
+        *,
+        policy: Policy | None = None,
+        infer_schema: bool = False,
+    ) -> None:
+        self._tools[name] = fn
+        if schema is not None:
+            self._schemas[name] = schema
+        elif infer_schema:
+            self._schemas[name] = schema_from_signature(fn)
+        if policy is not None:
+            self._policies[name] = policy
+
+    def get(self, name: str) -> ToolFn | None:
+        return self._tools.get(name)
+
+    def get_schema(self, name: str) -> ToolSchema | None:
+        return self._schemas.get(name)
+
+    def get_policy(self, name: str) -> Policy | None:
+        return self._policies.get(name)
+
+    def names(self) -> list[str]:
+        return list(self._tools.keys())
+
+
+@dataclass
+class GateResult:
+    verdict: Verdict
+    call: ToolCall | None = None
+    reasons: list[str] = field(default_factory=list)
+    executed: bool = False
+    return_value: Any = None
+    error: str | None = None
+    findings: list[Finding] = field(default_factory=list)  # shield hits (value-free)
+    dry_run: bool = False  # True when the gate simulated execution
+
+    @property
+    def allowed(self) -> bool:
+        return self.verdict is Verdict.ALLOW
+
+
+class Gate:
+    """Fail-closed gate.
+
+    default="deny"  -> a registered tool with NO schema is still blocked
+    default="allow" -> schema optional; registered tool without schema passes
+
+    approval: optional handler called by run()/run_all() when a policy demands
+    approval. Returns True to execute. Without a handler, NEEDS_APPROVAL calls
+    are never executed (fail closed).
+    """
+
+    def __init__(
+        self,
+        registry: ToolRegistry | None = None,
+        *,
+        default: DefaultMode = "deny",
+        meter: Meter | None = None,
+        shield: Shield | None = None,
+        approval: ApprovalHandler | None = None,
+        dry_run: bool = False,
+        lane: str = "gate",
+    ):
+        if default not in ("deny", "allow"):
+            raise ValueError(f"default must be 'deny' or 'allow', got {default!r}")
+        self.registry = registry or ToolRegistry()
+        self.default = default
+        self.meter = meter
+        self.shield = shield
+        self.approval = approval
+        self.dry_run = dry_run
+        self.lane = lane
+        self.history: list[GateResult] = []  # every checked result, for reports/suggest
+        self._budget: dict[str, Any] = {}
+        self._executed_calls = 0
+        self._executed_per_tool: dict[str, int] = {}
+
+    def register(
+        self,
+        name: str,
+        fn: ToolFn,
+        schema: ToolSchema | None = None,
+        *,
+        policy: Policy | None = None,
+        infer_schema: bool = False,
+    ) -> None:
+        self.registry.register(name, fn, schema, policy=policy, infer_schema=infer_schema)
+
+    # -- budget ---------------------------------------------------------------
+
+    def budget(
+        self,
+        *,
+        max_calls: int | None = None,
+        max_calls_per_tool: int | None = None,
+        max_usd: float | None = None,
+    ) -> None:
+        if max_usd is not None and self.meter is None:
+            raise ValueError("max_usd budget requires a meter (cost is meter-derived)")
+        self._budget = {
+            "max_calls": max_calls,
+            "max_calls_per_tool": max_calls_per_tool,
+            "max_usd": max_usd,
+        }
+
+    def _budget_violation(self, call: ToolCall) -> str | None:
+        if not self._budget:
+            return None
+        max_calls = self._budget.get("max_calls")
+        if max_calls is not None and self._executed_calls >= max_calls:
+            return f"budget exceeded: max_calls={max_calls} already executed"
+        per_tool = self._budget.get("max_calls_per_tool")
+        if per_tool is not None and self._executed_per_tool.get(call.name, 0) >= per_tool:
+            return f"budget exceeded: max_calls_per_tool={per_tool} for {call.name!r}"
+        max_usd = self._budget.get("max_usd")
+        if max_usd is not None and self.meter is not None:
+            spent = self.meter.report.estimate_cost_usd(self.lane)
+            if spent >= max_usd:
+                return f"budget exceeded: estimated ${spent:.4f} >= max_usd={max_usd}"
+        return None
+
+    # -- checking ---------------------------------------------------------------
+
+    def check_all(self, payload: Any) -> list[GateResult]:
+        try:
+            calls = parse_tool_calls(payload)
+        except IntakeError as exc:
+            return [self._record(GateResult(Verdict.BLOCK, reasons=[f"intake: {exc}"]))]
+        if not calls:
+            return [self._record(GateResult(Verdict.BLOCK, reasons=["intake: no tool calls in payload"]))]
+        return [self._check_one(call) for call in calls]
+
+    def check(self, payload: Any) -> GateResult:
+        results = self.check_all(payload)
+        if len(results) != 1:
+            raise ValueError(f"expected exactly 1 tool call, got {len(results)}; use check_all()")
+        return results[0]
+
+    def _check_one(self, call: ToolCall) -> GateResult:
+        if self.registry.get(call.name) is None:
+            return self._record(GateResult(Verdict.BLOCK, call, [f"unknown tool: {call.name!r}"]))
+
+        budget_reason = self._budget_violation(call)
+        if budget_reason is not None:
+            return self._record(GateResult(Verdict.BLOCK, call, [budget_reason]))
+
+        schema = self.registry.get_schema(call.name)
+        if schema is None:
+            if self.default == "deny":
+                return self._record(
+                    GateResult(
+                        Verdict.BLOCK,
+                        call,
+                        [f"no schema registered for {call.name!r} and gate default is deny"],
+                    )
+                )
+        else:
+            errors = schema.validate(call.args)
+            if errors:
+                return self._record(GateResult(Verdict.BLOCK, call, errors))
+
+        policy = self.registry.get_policy(call.name)
+        if policy is not None:
+            errors = policy.validate(call.args)
+            if errors:
+                return self._record(GateResult(Verdict.BLOCK, call, errors))
+
+        findings: list[Finding] = []
+        if self.shield is not None:
+            if self.shield.mode == "redact":
+                call.args, findings = self.shield.redact_args(call.args)
+            else:
+                findings = self.shield.scan_args(call.args)
+                if findings and self.shield.mode == "block":
+                    reasons = [
+                        f"secret detected ({f.kind}) in arg {f.arg!r}" for f in findings
+                    ]
+                    return self._record(
+                        GateResult(Verdict.BLOCK, call, reasons, findings=findings)
+                    )
+
+        if policy is not None and policy.require_approval:
+            return self._record(
+                GateResult(
+                    Verdict.NEEDS_APPROVAL,
+                    call,
+                    [f"approval required for {call.name!r}"],
+                    findings=findings,
+                )
+            )
+
+        return self._record(GateResult(Verdict.ALLOW, call, findings=findings))
+
+    # -- execution ----------------------------------------------------------------
+
+    def execute(self, result: GateResult) -> GateResult:
+        if not result.allowed or result.call is None:
+            joined = "; ".join(result.reasons) or "no call"
+            raise PermissionError(f"refusing to execute a {result.verdict.value} result: {joined}")
+        self._executed_calls += 1
+        self._executed_per_tool[result.call.name] = (
+            self._executed_per_tool.get(result.call.name, 0) + 1
+        )
+        if self.dry_run:
+            result.dry_run = True
+            if self.meter is not None:
+                self.meter.record(
+                    RunEvent(
+                        lane=self.lane,
+                        kind="tool",
+                        ok=True,
+                        namespace=result.call.name,
+                        meta={"dry_run": True, "would_execute": True},
+                    )
+                )
+            return result
+        tool = self.registry.get(result.call.name)
+        if tool is None:  # registry mutated between check and execute
+            result.error = f"unknown tool at execute time: {result.call.name!r}"
+        else:
+            try:
+                result.return_value = tool(**result.call.args)
+                result.executed = True
+            except Exception as exc:
+                result.error = f"{type(exc).__name__}: {exc}"
+        if self.meter is not None:
+            self.meter.record(
+                RunEvent(
+                    lane=self.lane,
+                    kind="tool",
+                    ok=result.executed,
+                    namespace=result.call.name,
+                    error=result.error,
+                )
+            )
+        return result
+
+    def _resolve_approval(self, result: GateResult) -> GateResult:
+        """Called by run/run_all on NEEDS_APPROVAL. Fail closed without a handler."""
+        if self.approval is None:
+            return result
+        try:
+            granted = bool(self.approval(result))
+        except Exception as exc:
+            result.verdict = Verdict.BLOCK
+            result.reasons.append(f"approval handler raised {type(exc).__name__}: fails closed")
+            return self._record_transition(result, "approval-error")
+        if granted:
+            result.verdict = Verdict.ALLOW
+            result.reasons = []
+            return self._record_transition(result, "approval-granted")
+        result.verdict = Verdict.BLOCK
+        result.reasons.append("approval denied")
+        return self._record_transition(result, "approval-denied")
+
+    def run(self, payload: Any) -> GateResult:
+        result = self.check(payload)
+        if result.verdict is Verdict.NEEDS_APPROVAL:
+            result = self._resolve_approval(result)
+        if result.allowed:
+            return self.execute(result)
+        return result
+
+    def run_all(self, payload: Any) -> list[GateResult]:
+        out: list[GateResult] = []
+        for result in self.check_all(payload):
+            if result.verdict is Verdict.NEEDS_APPROVAL:
+                result = self._resolve_approval(result)
+            out.append(self.execute(result) if result.allowed else result)
+        return out
+
+    # -- reporting ----------------------------------------------------------------
+
+    def report(self) -> dict[str, Any]:
+        """Summary of everything this gate has seen. Useful after a dry run."""
+        by_verdict: dict[str, int] = {}
+        by_tool: dict[str, dict[str, int]] = {}
+        blocked_reasons: list[str] = []
+        finding_kinds: dict[str, int] = {}
+        for r in self.history:
+            by_verdict[r.verdict.value] = by_verdict.get(r.verdict.value, 0) + 1
+            name = r.call.name if r.call else "(unparsed)"
+            tool_row = by_tool.setdefault(name, {"allow": 0, "block": 0, "needs_approval": 0})
+            tool_row[r.verdict.value] = tool_row.get(r.verdict.value, 0) + 1
+            if r.verdict is Verdict.BLOCK and r.reasons:
+                blocked_reasons.append(f"{name}: {r.reasons[0]}")
+            for f in r.findings:
+                finding_kinds[f.kind] = finding_kinds.get(f.kind, 0) + 1
+        return {
+            "dry_run": self.dry_run,
+            "calls_checked": len(self.history),
+            "verdicts": by_verdict,
+            "would_execute" if self.dry_run else "executed": self._executed_calls,
+            "by_tool": by_tool,
+            "blocked_reasons": blocked_reasons,
+            "secret_findings_by_kind": finding_kinds,
+        }
+
+    # -- internals -------------------------------------------------------------------
+
+    def _record(self, result: GateResult) -> GateResult:
+        self.history.append(result)
+        if self.meter is not None:
+            self.meter.record_intercept(
+                lane=self.lane,
+                ok=result.verdict is Verdict.ALLOW,
+                namespace=result.call.name if result.call else None,
+                error="; ".join(result.reasons) or None,
+                meta={
+                    "verdict": result.verdict.value,
+                    "default": self.default,
+                    "findings": [f.kind for f in result.findings],
+                },
+            )
+        return result
+
+    def _record_transition(self, result: GateResult, event: str) -> GateResult:
+        if self.meter is not None:
+            self.meter.record(
+                RunEvent(
+                    lane=self.lane,
+                    kind="note",
+                    ok=result.verdict is Verdict.ALLOW,
+                    namespace=result.call.name if result.call else None,
+                    meta={"approval": event},
+                )
+            )
+        return result

toolwall/intake.py

@@ -0,0 +1,177 @@
+"""Normalize LLM provider tool-call outputs into ToolCall records.
+
+Accepted shapes (dicts, or SDK objects exposing model_dump()/to_dict()):
+
+- Plain call:        {"name"|"tool"|"action": str, "args"|"params"|"arguments"|"input": {...}}
+- OpenAI chat:       choices[*].message.tool_calls[*].function{name, arguments(JSON str)}
+- OpenAI responses:  output[*] where type == "function_call" {name, arguments(JSON str)}
+- Anthropic:         content[*] where type == "tool_use" {name, input}
+- Gemini:            candidates[*].content.parts[*].functionCall|function_call {name, args}
+
+No provider SDK is imported here — toolwall core stays stdlib-only.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class IntakeError(ValueError):
+    """Payload could not be interpreted as tool call(s)."""
+
+
+@dataclass
+class ToolCall:
+    name: str
+    args: dict[str, Any] = field(default_factory=dict)
+    id: str | None = None
+    source: str = "dict"
+
+
+_NAME_KEYS = ("name", "tool", "tool_name", "action", "namespace")
+_ARG_KEYS = ("args", "params", "arguments", "parameters", "input", "inputs")
+
+
+def _as_data(obj: Any) -> Any:
+    if isinstance(obj, (dict, list)):
+        return obj
+    for attr in ("model_dump", "to_dict", "to_json_dict"):
+        fn = getattr(obj, attr, None)
+        if callable(fn):
+            try:
+                data = fn()
+            except TypeError:
+                continue
+            if isinstance(data, (dict, list)):
+                return data
+    raise IntakeError(f"unsupported payload type: {type(obj).__name__}")
+
+
+def _parse_args(value: Any) -> dict[str, Any]:
+    if value is None:
+        return {}
+    if isinstance(value, str):
+        try:
+            value = json.loads(value or "{}")
+        except json.JSONDecodeError as exc:
+            raise IntakeError(f"tool arguments are not valid JSON: {exc}") from exc
+    if not isinstance(value, dict):
+        raise IntakeError(f"tool args must be an object, got {type(value).__name__}")
+    return value
+
+
+def _from_openai_chat(data: dict) -> list[ToolCall] | None:
+    choices = data.get("choices")
+    if not isinstance(choices, list):
+        return None
+    calls: list[ToolCall] = []
+    for choice in choices:
+        message = (choice or {}).get("message") or {}
+        for tc in message.get("tool_calls") or []:
+            fn = tc.get("function") or {}
+            name = fn.get("name")
+            if not name:
+                raise IntakeError("OpenAI tool_call missing function.name")
+            calls.append(
+                ToolCall(name=name, args=_parse_args(fn.get("arguments")), id=tc.get("id"), source="openai-chat")
+            )
+    return calls
+
+
+def _from_openai_responses(data: dict) -> list[ToolCall] | None:
+    output = data.get("output")
+    if not isinstance(output, list):
+        return None
+    calls: list[ToolCall] = []
+    for item in output:
+        if isinstance(item, dict) and item.get("type") == "function_call":
+            name = item.get("name")
+            if not name:
+                raise IntakeError("OpenAI responses function_call missing name")
+            calls.append(
+                ToolCall(
+                    name=name,
+                    args=_parse_args(item.get("arguments")),
+                    id=item.get("call_id") or item.get("id"),
+                    source="openai-responses",
+                )
+            )
+    return calls
+
+
+def _from_anthropic(data: dict) -> list[ToolCall] | None:
+    content = data.get("content")
+    if not isinstance(content, list):
+        return None
+    calls: list[ToolCall] = []
+    for block in content:
+        if isinstance(block, dict) and block.get("type") == "tool_use":
+            name = block.get("name")
+            if not name:
+                raise IntakeError("Anthropic tool_use block missing name")
+            calls.append(
+                ToolCall(name=name, args=_parse_args(block.get("input")), id=block.get("id"), source="anthropic")
+            )
+    return calls
+
+
+def _from_gemini(data: dict) -> list[ToolCall] | None:
+    candidates = data.get("candidates")
+    if not isinstance(candidates, list):
+        return None
+    calls: list[ToolCall] = []
+    for cand in candidates:
+        parts = ((cand or {}).get("content") or {}).get("parts") or []
+        for part in parts:
+            if not isinstance(part, dict):
+                continue
+            fc = part.get("functionCall") or part.get("function_call")
+            if fc:
+                name = fc.get("name")
+                if not name:
+                    raise IntakeError("Gemini functionCall missing name")
+                calls.append(ToolCall(name=name, args=_parse_args(fc.get("args")), source="gemini"))
+    return calls
+
+
+def _from_plain(data: dict) -> ToolCall | None:
+    name = next((data[k] for k in _NAME_KEYS if isinstance(data.get(k), str)), None)
+    if name is None:
+        return None
+    raw_args = next((data[k] for k in _ARG_KEYS if k in data), None)
+    return ToolCall(name=name, args=_parse_args(raw_args), id=data.get("id"), source="dict")
+
+
+_ENVELOPE_EXTRACTORS = (_from_openai_chat, _from_openai_responses, _from_anthropic, _from_gemini)
+
+
+def parse_tool_calls(payload: Any) -> list[ToolCall]:
+    """Extract every tool call from a provider response or plain dict.
+
+    Returns [] when a recognized envelope contains no tool calls
+    (e.g. the model answered with plain text). Raises IntakeError when
+    the payload shape is not recognizable at all.
+    """
+    data = _as_data(payload)
+
+    if isinstance(data, list):
+        calls: list[ToolCall] = []
+        for item in data:
+            calls.extend(parse_tool_calls(item))
+        return calls
+
+    for extract in _ENVELOPE_EXTRACTORS:
+        calls = extract(data)
+        if calls is not None:
+            return calls
+
+    plain = _from_plain(data)
+    if plain is not None:
+        return [plain]
+
+    raise IntakeError(
+        "no recognizable tool-call shape (expected OpenAI/Anthropic/Gemini response or "
+        f"a dict with one of {_NAME_KEYS})"
+    )