agent-loop-guard-runtime 0.6.0a2__py3-none-any.whl

app/core/config.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def _bool(value: str | bool | None, default: bool = False) -> bool:
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        return value
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _int(value: str | int | None, default: int) -> int:
+    if value is None:
+        return default
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _get(data: dict[str, Any], path: str, default: Any = None) -> Any:
+    current: Any = data
+    for part in path.split("."):
+        if not isinstance(current, dict) or part not in current:
+            return default
+        current = current[part]
+    return current
+
+
+@dataclass(slots=True)
+class AppConfig:
+    host: str = "127.0.0.1"
+    port: int = 8787
+    admin_ui: bool = True
+    storage_url: str = "sqlite:///./data/agent_loop_guard.db"
+    retention_days: int = 30
+    full_content_logging: bool = False
+    body_limit_bytes: int = 1_048_576
+    inactive_timeout_seconds: int = 1800
+    default_project_id: str = "default"
+    default_mode: str = "shadow"
+    default_provider: str = "mock"
+    allow_mode_header: bool = True
+    gateway_key: str = "alg_demo_key"
+    openai_base_url: str = "https://api.openai.com/v1"
+    openai_api_key: str | None = None
+    anthropic_base_url: str = "https://api.anthropic.com"
+    anthropic_api_key: str | None = None
+    mcp_policy_path: str = "mcp-policy.yml"
+    mcp_approval_timeout_seconds: int = 30
+    mcp_allowed_origins: list[str] = field(
+        default_factory=lambda: ["http://127.0.0.1", "http://localhost"]
+    )
+    mcp_servers: dict[str, dict[str, Any]] = field(
+        default_factory=lambda: {
+            "filesystem": {
+                "name": "Demo filesystem server",
+                "transport": "mock",
+                "target": "mock://filesystem",
+            }
+        }
+    )
+
+    @classmethod
+    def from_env(cls) -> AppConfig:
+        defaults = cls()
+        data: dict[str, Any] = {}
+        config_path = os.getenv("ALG_CONFIG")
+        if config_path and Path(config_path).exists():
+            with open(config_path, encoding="utf-8") as fh:
+                data = yaml.safe_load(fh) or {}
+
+        return cls(
+            host=os.getenv("ALG_HOST", str(_get(data, "server.host", defaults.host))),
+            port=_int(os.getenv("ALG_PORT"), int(_get(data, "server.port", defaults.port))),
+            admin_ui=_bool(os.getenv("ALG_ADMIN_UI"), bool(_get(data, "server.admin_ui", True))),
+            storage_url=os.getenv(
+                "ALG_STORAGE_URL", str(_get(data, "storage.url", defaults.storage_url))
+            ),
+            retention_days=_int(
+                os.getenv("ALG_RETENTION_DAYS"),
+                int(_get(data, "storage.retention_days", defaults.retention_days)),
+            ),
+            full_content_logging=_bool(
+                os.getenv("ALG_FULL_CONTENT_LOGGING"),
+                bool(_get(data, "storage.full_content_logging", False)),
+            ),
+            body_limit_bytes=_int(
+                os.getenv("ALG_BODY_LIMIT_BYTES"),
+                int(_get(data, "server.body_limit_bytes", defaults.body_limit_bytes)),
+            ),
+            inactive_timeout_seconds=_int(
+                os.getenv("ALG_INACTIVE_TIMEOUT_SECONDS"),
+                int(
+                    _get(
+                        data,
+                        "server.inactive_timeout_seconds",
+                        defaults.inactive_timeout_seconds,
+                    )
+                ),
+            ),
+            default_mode=os.getenv("ALG_MODE", str(_get(data, "projects.default.mode", "shadow"))),
+            default_provider=os.getenv(
+                "ALG_PROVIDER", str(_get(data, "projects.default.provider", "mock"))
+            ),
+            allow_mode_header=_bool(
+                os.getenv("ALG_ALLOW_MODE_HEADER"),
+                bool(_get(data, "server.allow_mode_header", True)),
+            ),
+            gateway_key=os.getenv(
+                "ALG_GATEWAY_KEY", str(_get(data, "gateway_key", defaults.gateway_key))
+            ),
+            openai_base_url=os.getenv(
+                "ALG_OPENAI_BASE_URL",
+                str(_get(data, "providers.openai.base_url", "https://api.openai.com/v1")),
+            ),
+            openai_api_key=os.getenv(
+                "OPENAI_API_KEY", _get(data, "providers.openai.api_key", None)
+            ),
+            anthropic_base_url=os.getenv(
+                "ALG_ANTHROPIC_BASE_URL",
+                str(_get(data, "providers.anthropic.base_url", "https://api.anthropic.com")),
+            ),
+            anthropic_api_key=os.getenv(
+                "ANTHROPIC_API_KEY", _get(data, "providers.anthropic.api_key", None)
+            ),
+            mcp_policy_path=os.getenv(
+                "ALG_MCP_POLICY", str(_get(data, "mcp.policy", defaults.mcp_policy_path))
+            ),
+            mcp_approval_timeout_seconds=_int(
+                os.getenv("ALG_MCP_APPROVAL_TIMEOUT_SECONDS"),
+                int(_get(data, "mcp.approval_timeout_seconds", 30)),
+            ),
+            mcp_allowed_origins=list(
+                _get(data, "mcp.allowed_origins", defaults.mcp_allowed_origins)
+            ),
+            mcp_servers=dict(_get(data, "mcp.servers", defaults.mcp_servers)),
+        )
+
+    def ensure_storage_parent(self) -> None:
+        if not self.storage_url.startswith("sqlite:///"):
+            return
+        raw_path = self.storage_url.removeprefix("sqlite:///")
+        if raw_path == ":memory:":
+            return
+        path = Path(raw_path)
+        if not path.is_absolute():
+            path = Path.cwd() / path
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+
+SAMPLE_CONFIG = """server:
+  host: 127.0.0.1
+  port: 8787
+  admin_ui: true
+  body_limit_bytes: 1048576
+  inactive_timeout_seconds: 1800
+storage:
+  url: sqlite:///./data/agent_loop_guard.db
+  retention_days: 30
+  full_content_logging: false
+gateway_key: alg_demo_key
+projects:
+  default:
+    mode: shadow
+    provider: mock
+providers:
+  mock:
+    type: mock
+  openai:
+    type: openai
+    base_url: https://api.openai.com/v1
+    api_key_env: OPENAI_API_KEY
+  anthropic:
+    type: anthropic
+    base_url: https://api.anthropic.com
+    api_key_env: ANTHROPIC_API_KEY
+mcp:
+  policy: mcp-policy.yml
+  approval_timeout_seconds: 30
+  allowed_origins:
+    - http://127.0.0.1
+    - http://localhost
+  servers:
+    filesystem:
+      name: Demo filesystem server
+      transport: mock
+      target: mock://filesystem
+"""

app/core/demo.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from typing import Any
+
+from app.core.loop_detector import error_fingerprint, request_fingerprint, tool_call_fingerprints
+from app.core.policy_engine import PolicyDecision, evaluate
+from app.core.redaction import safe_preview
+from app.core.token_meter import usage_or_estimate
+from app.db.models import Agent, GuardSession
+from app.db.repository import Repository
+
+
+def _body_for(scenario: str, index: int) -> dict[str, Any]:
+    if scenario == "normal":
+        return {"model": "demo-model", "input": f"Write a short unique demo line {index}."}
+    if scenario == "tool-loop":
+        return {
+            "model": "demo-model",
+            "messages": [{"role": "user", "content": "Inspect the same file again."}],
+            "tool_calls": [{"tool_name": "read_file", "arguments": {"path": "README.md"}}],
+        }
+    if scenario == "error-retry":
+        return {
+            "model": "demo-model",
+            "messages": [{"role": "user", "content": "Retry the failing upstream call."}],
+            "mock_status": 500,
+            "mock_error": "deterministic demo failure",
+        }
+    if scenario == "streaming":
+        return {"model": "demo-model", "input": f"Stream demo chunk {index}.", "stream": True}
+    return {"model": "demo-model", "input": "Repeat this exact request."}
+
+
+def _event(repo: Repository, session: GuardSession, request_id: str, decision: PolicyDecision) -> None:
+    if decision.reason_code:
+        repo.event(
+            session.id,
+            request_id,
+            "policy_triggered",
+            "error" if decision.blocked else "warning",
+            decision.reason_code,
+            decision.mode,
+            decision.details or {},
+            decision.rule_id,
+        )
+
+
+def run_demo(repo: Repository, agent: Agent, scenario: str, mode: str) -> GuardSession:
+    scenario = scenario if scenario in {"normal", "exact-loop", "tool-loop", "error-retry", "streaming"} else "exact-loop"
+    count = {"normal": 12, "error-retry": 5, "streaming": 3}.get(scenario, 3)
+    session = repo.get_or_create_session(agent.project_id, agent.id, f"demo-{scenario}", 0)
+    if session.status == "paused":
+        session.status = "active"
+    policies = repo.policies(agent.project_id)
+    previous_error: tuple[str | None, int] = (None, 0)
+
+    for index in range(count):
+        body = _body_for(scenario, index)
+        req_fp = request_fingerprint(body)
+        tools = tool_call_fingerprints(body)
+        decision = evaluate(
+            mode=mode,
+            session=session,
+            agent=agent,
+            policies=policies,
+            request_fp=req_fp,
+            tool_fps=[f"{name}:{args_hash}" for name, args_hash in tools],
+            recent_request_fps=repo.recent_request_fingerprints(session.id, 30),
+            recent_tool_fps=repo.recent_tool_fingerprints(session.id, 30),
+            last_error_count=repo.consecutive_error_count(session.id)[1],
+        )
+        status = 500 if scenario == "error-retry" else decision.http_status if decision.blocked else 200
+        response: dict[str, Any] = {"ok": status < 400, "demo": scenario, "index": index}
+        err_fp = None
+        if scenario == "error-retry":
+            response = {"error": {"type": "mock_error", "message": "deterministic demo failure"}}
+            err_fp = error_fingerprint(status, response)
+            previous_fp, previous_count = previous_error
+            current_count = previous_count + 1 if previous_fp == err_fp else 1
+            previous_error = (err_fp, current_count)
+            if current_count >= 5 and not decision.reason_code:
+                decision = PolicyDecision(
+                    decision="shadow_flag",
+                    mode=mode,
+                    reason_code="LOOP_ERROR_RETRY",
+                    rule_id="rule_error_retry",
+                    message="The same upstream error repeated consecutively.",
+                    details={"count": current_count, "threshold": 5, "fingerprint": err_fp},
+                )
+        record = repo.record_request(
+            session=session,
+            protocol="openai",
+            endpoint="/api/demo/run",
+            model=str(body.get("model")),
+            fingerprint=req_fp,
+            status=status,
+            latency_ms=1,
+            tokens=usage_or_estimate("openai", body, response),
+            decision=decision.decision,
+            reason_code=decision.reason_code,
+            request_preview=safe_preview(body, False),
+            response_preview=safe_preview(response, False),
+            tool_calls=tools,
+            error_fingerprint=err_fp,
+        )
+        _event(repo, session, record.id, decision)
+        session = repo.get_session(session.id) or session
+    return session
+

app/core/loop_detector.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from typing import Any
+
+DEFAULT_IGNORE_KEYS = {
+    "id",
+    "request_id",
+    "created",
+    "created_at",
+    "updated_at",
+    "timestamp",
+    "trace_id",
+}
+
+
+def _normalize_string(value: str) -> str:
+    return re.sub(r"\s+", " ", value).strip()
+
+
+def _canonical(value: Any, ignore_keys: set[str]) -> Any:
+    if isinstance(value, dict):
+        return {
+            key: _canonical(value[key], ignore_keys)
+            for key in sorted(value)
+            if key not in ignore_keys
+        }
+    if isinstance(value, list):
+        return [_canonical(item, ignore_keys) for item in value]
+    if isinstance(value, str):
+        return _normalize_string(value)
+    return value
+
+
+def canonical_json(value: Any, ignore_keys: set[str] | None = None) -> str:
+    ignore = DEFAULT_IGNORE_KEYS if ignore_keys is None else DEFAULT_IGNORE_KEYS | ignore_keys
+    return json.dumps(_canonical(value, ignore), sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def sha256_text(value: str) -> str:
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()
+
+
+def relevant_request_body(body: dict[str, Any]) -> dict[str, Any]:
+    selected: dict[str, Any] = {}
+    for key in ("model", "messages", "input", "system", "tools", "tool_choice"):
+        if key in body:
+            selected[key] = body[key]
+    return selected
+
+
+def request_fingerprint(body: dict[str, Any], ignore_keys: set[str] | None = None) -> str:
+    return sha256_text(canonical_json(relevant_request_body(body), ignore_keys))
+
+
+def _canonical_arg_hash(value: Any) -> str:
+    if isinstance(value, str):
+        try:
+            parsed = json.loads(value)
+        except json.JSONDecodeError:
+            parsed = value
+    else:
+        parsed = value
+    return sha256_text(canonical_json(parsed))
+
+
+def tool_call_fingerprints(body: Any) -> list[tuple[str, str]]:
+    calls: list[tuple[str, str]] = []
+
+    def walk(value: Any) -> None:
+        if isinstance(value, dict):
+            function = value.get("function")
+            if isinstance(function, dict) and "name" in function:
+                calls.append((str(function["name"]), _canonical_arg_hash(function.get("arguments", {}))))
+            elif value.get("type") == "tool_use" and "name" in value:
+                calls.append((str(value["name"]), _canonical_arg_hash(value.get("input", {}))))
+            elif "tool_name" in value and ("arguments" in value or "args" in value or "input" in value):
+                args = value.get("arguments", value.get("args", value.get("input", {})))
+                calls.append((str(value["tool_name"]), _canonical_arg_hash(args)))
+            for item in value.values():
+                walk(item)
+        elif isinstance(value, list):
+            for item in value:
+                walk(item)
+
+    walk(body)
+    return calls
+
+
+def error_fingerprint(status_code: int, body: Any) -> str:
+    error_type = None
+    message = None
+    if isinstance(body, dict):
+        error = body.get("error", body)
+        if isinstance(error, dict):
+            error_type = error.get("type") or error.get("code")
+            message = error.get("message") or error.get("detail")
+    if message is None:
+        message = str(body)
+    normalized = {
+        "status": status_code,
+        "type": _normalize_string(str(error_type or "unknown")),
+        "message": _normalize_string(str(message))[:500],
+    }
+    return sha256_text(canonical_json(normalized))
+
+
+def repeated_sequence(sequence: list[str], min_len: int = 2, max_len: int = 5, repeats: int = 3) -> bool:
+    if len(sequence) < min_len * repeats:
+        return False
+    upper = min(max_len, len(sequence) // repeats)
+    for size in range(min_len, upper + 1):
+        suffix = sequence[-size * repeats :]
+        pattern = suffix[:size]
+        if all(suffix[i : i + size] == pattern for i in range(0, len(suffix), size)):
+            return True
+    return False
+

app/core/policy_engine.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from app.core.loop_detector import repeated_sequence
+from app.db.models import Agent, GuardSession, Policy
+
+REASON_BY_RULE = {
+    "exact_repeat": "LOOP_EXACT",
+    "tool_repeat": "LOOP_TOOL_CALL",
+    "error_retry": "LOOP_ERROR_RETRY",
+    "sequence_repeat": "LOOP_SEQUENCE",
+    "max_requests": "LIMIT_REQUESTS",
+    "max_tokens": "LIMIT_TOKENS",
+}
+
+MESSAGE_BY_REASON = {
+    "LOOP_EXACT": "The same normalized request repeated in the recent window.",
+    "LOOP_TOOL_CALL": "The same tool call and arguments repeated in the recent window.",
+    "LOOP_ERROR_RETRY": "The same upstream error repeated consecutively.",
+    "LOOP_SEQUENCE": "A short sequence of request fingerprints repeated.",
+    "LIMIT_REQUESTS": "The session request limit has been reached.",
+    "LIMIT_TOKENS": "The session token limit has been reached.",
+    "SESSION_PAUSED": "The session is paused.",
+    "AGENT_PAUSED": "The agent key is paused.",
+}
+
+
+@dataclass(slots=True)
+class PolicyDecision:
+    decision: str
+    mode: str
+    reason_code: str | None = None
+    rule_id: str | None = None
+    message: str = "Allowed."
+    details: dict | None = None
+    http_status: int = 200
+
+    @property
+    def blocked(self) -> bool:
+        return self.decision == "block"
+
+
+def _policy_map(policies: list[Policy]) -> dict[str, Policy]:
+    return {policy.rule_type: policy for policy in policies if policy.enabled}
+
+
+def _finish(mode: str, policy: Policy, reason_code: str, details: dict) -> PolicyDecision:
+    decision = "shadow_flag"
+    status = 200
+    if mode == "enforce" and policy.action == "block":
+        decision = "block"
+        status = 429
+    return PolicyDecision(
+        decision=decision,
+        mode=mode,
+        reason_code=reason_code,
+        rule_id=policy.id,
+        message=MESSAGE_BY_REASON[reason_code],
+        details=details,
+        http_status=status,
+    )
+
+
+def evaluate(
+    *,
+    mode: str,
+    session: GuardSession,
+    agent: Agent,
+    policies: list[Policy],
+    request_fp: str,
+    tool_fps: list[str],
+    recent_request_fps: list[str],
+    recent_tool_fps: list[str],
+    last_error_count: int,
+) -> PolicyDecision:
+    mode = "enforce" if mode == "enforce" else "shadow"
+
+    if agent.paused:
+        return PolicyDecision(
+            decision="block",
+            mode=mode,
+            reason_code="AGENT_PAUSED",
+            rule_id="manual_agent_pause",
+            message=MESSAGE_BY_REASON["AGENT_PAUSED"],
+            details={},
+            http_status=409,
+        )
+    if session.status == "paused":
+        return PolicyDecision(
+            decision="block",
+            mode=mode,
+            reason_code="SESSION_PAUSED",
+            rule_id="manual_session_pause",
+            message=MESSAGE_BY_REASON["SESSION_PAUSED"],
+            details={},
+            http_status=409,
+        )
+
+    rules = _policy_map(policies)
+
+    max_requests = rules.get("max_requests")
+    if max_requests and session.request_count >= max_requests.threshold:
+        return _finish(
+            mode,
+            max_requests,
+            "LIMIT_REQUESTS",
+            {"count": session.request_count, "threshold": max_requests.threshold},
+        )
+
+    max_tokens = rules.get("max_tokens")
+    if max_tokens and session.total_tokens >= max_tokens.threshold:
+        return _finish(
+            mode,
+            max_tokens,
+            "LIMIT_TOKENS",
+            {"tokens": session.total_tokens, "threshold": max_tokens.threshold},
+        )
+
+    exact = rules.get("exact_repeat")
+    if exact:
+        window = max(1, exact.window_size - 1)
+        recent = recent_request_fps[-window:]
+        count = recent.count(request_fp) + 1
+        if count >= exact.threshold:
+            return _finish(
+                mode,
+                exact,
+                "LOOP_EXACT",
+                {"count": count, "window": exact.window_size, "fingerprint": request_fp},
+            )
+
+    tool = rules.get("tool_repeat")
+    if tool and tool_fps:
+        recent = recent_tool_fps[-tool.window_size :]
+        for fp in tool_fps:
+            count = recent.count(fp) + tool_fps.count(fp)
+            if count >= tool.threshold:
+                return _finish(
+                    mode,
+                    tool,
+                    "LOOP_TOOL_CALL",
+                    {"count": count, "window": tool.window_size, "fingerprint": fp},
+                )
+
+    error_retry = rules.get("error_retry")
+    if error_retry and last_error_count >= error_retry.threshold:
+        return _finish(
+            mode,
+            error_retry,
+            "LOOP_ERROR_RETRY",
+            {"count": last_error_count, "threshold": error_retry.threshold},
+        )
+
+    sequence = rules.get("sequence_repeat")
+    if sequence:
+        values = recent_request_fps[-sequence.window_size :] + [request_fp]
+        if repeated_sequence(values, repeats=sequence.threshold):
+            return _finish(
+                mode,
+                sequence,
+                "LOOP_SEQUENCE",
+                {"window": sequence.window_size, "threshold": sequence.threshold},
+            )
+
+    return PolicyDecision(decision="allow", mode=mode)
+

app/core/redaction.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+SECRET_PATTERNS = [
+    re.compile(r"sk-[A-Za-z0-9_\-]{16,}"),
+    re.compile(r"sk-ant-[A-Za-z0-9_\-]{16,}"),
+    re.compile(r"gh[pousr]_[A-Za-z0-9_]{16,}"),
+    re.compile(r"xox[baprs]-[A-Za-z0-9\-]{16,}"),
+    re.compile(r"alg_[A-Za-z0-9_]{12,}"),
+    re.compile(r"(?i)(api[_-]?key|authorization|token|secret)\s*[:=]\s*['\"]?[^'\"\s,}]+"),
+]
+
+SENSITIVE_HEADERS = {
+    "authorization",
+    "x-api-key",
+    "api-key",
+    "anthropic-api-key",
+    "openai-api-key",
+    "proxy-authorization",
+}
+
+
+def redact_text(value: str | None) -> str | None:
+    if value is None:
+        return None
+    redacted = value
+    for pattern in SECRET_PATTERNS:
+        redacted = pattern.sub("[REDACTED]", redacted)
+    return redacted
+
+
+def redact_headers(headers: dict[str, str]) -> dict[str, str]:
+    safe: dict[str, str] = {}
+    for key, value in headers.items():
+        if key.lower() in SENSITIVE_HEADERS:
+            safe[key] = "[REDACTED]"
+        else:
+            safe[key] = redact_text(value) or ""
+    return safe
+
+
+def redact_value(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {
+            str(key): "[REDACTED]"
+            if str(key).lower() in SENSITIVE_HEADERS
+            or any(part in str(key).lower() for part in ("token", "secret", "password", "api_key"))
+            else redact_value(item)
+            for key, item in value.items()
+        }
+    if isinstance(value, list):
+        return [redact_value(item) for item in value]
+    if isinstance(value, tuple):
+        return [redact_value(item) for item in value]
+    if isinstance(value, str):
+        return redact_text(value)
+    return value
+
+
+def safe_preview(value: Any, full_content_logging: bool = False, max_chars: int = 500) -> str:
+    if not full_content_logging:
+        if isinstance(value, dict):
+            keys = ", ".join(sorted(str(k) for k in value.keys())[:12])
+            return f"metadata-only keys=[{keys}]"
+        return "metadata-only"
+    try:
+        text = json.dumps(value, ensure_ascii=False, sort_keys=True)
+    except TypeError:
+        text = str(value)
+    text = redact_text(text) or ""
+    if len(text) > max_chars:
+        return text[:max_chars] + "...[truncated]"
+    return text
+
+
+def safe_json_bytes(content: bytes, max_chars: int = 500) -> str:
+    text = content.decode("utf-8", errors="replace")
+    text = redact_text(text) or ""
+    if len(text) > max_chars:
+        return text[:max_chars] + "...[truncated]"
+    return text