agentloop-profiler 0.1.0__py3-none-any.whl

agentloop/interoperability/validation.py

@@ -0,0 +1,333 @@
+"""Bounded JSON and local artifact references for read-only import adapters."""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+import stat
+from dataclasses import dataclass, fields
+from hashlib import sha256
+from pathlib import Path, PureWindowsPath
+from typing import Any
+
+
+class ImportValidationError(ValueError):
+    """A payload-free diagnostic: never include untrusted values in messages."""
+
+    def __init__(self, code: str, field: str, reason: str) -> None:
+        self.code, self.field, self.reason = code, field, reason
+        super().__init__(f"{field}: {reason}")
+
+    def to_dict(self) -> dict[str, str]:
+        return {"code": self.code, "field": self.field, "reason": self.reason}
+
+
+@dataclass(frozen=True)
+class ImportLimits:
+    max_json_bytes: int = 8 * 1024 * 1024
+    max_line_bytes: int = 8 * 1024 * 1024
+    max_total_bytes: int = 512 * 1024 * 1024
+    max_records: int = 10_000
+    max_depth: int = 64
+    max_nodes: int = 200_000
+    max_trials: int = 10_000
+    max_trajectories: int = 256
+    max_spans: int = 100_000
+    max_events_per_trace: int = 10_000
+    max_references: int = 1_024
+    max_path_depth: int = 32
+    max_metadata_bytes: int = 64 * 1024
+    max_number_chars: int = 128
+
+    def __post_init__(self) -> None:
+        for item in fields(self):
+            value = getattr(self, item.name)
+            if type(value) is not int or value <= 0:
+                raise ImportValidationError(
+                    "invalid_limit", item.name, "must be a positive integer"
+                )
+        # The JSON decoder is recursive. Raising this setting must not bypass
+        # the preflight protection or expose platform-dependent recursion limits.
+        if self.max_depth > 128:
+            raise ImportValidationError("invalid_limit", "max_depth", "must not exceed 128")
+
+
+@dataclass
+class ImportBudget:
+    """Shared counters for adapters; rejected records still consume read bytes."""
+
+    limits: ImportLimits
+    total_bytes: int = 0
+    records: int = 0
+    trials: int = 0
+    trajectories: int = 0
+    spans: int = 0
+    references: int = 0
+
+    def consume(self, **counts: int) -> None:
+        pending = {}
+        for key, count in counts.items():
+            if key not in {
+                "total_bytes",
+                "records",
+                "trials",
+                "trajectories",
+                "spans",
+                "references",
+            }:
+                raise ImportValidationError("invalid_counter", "budget", "unknown counter")
+            if type(count) is not int or count < 0:
+                raise ImportValidationError(
+                    "invalid_counter", "budget", "count must be nonnegative"
+                )
+            value = getattr(self, key) + count
+            if value > getattr(self.limits, "max_" + key):
+                raise ImportValidationError("limit_exceeded", key, "import budget exceeded")
+            pending[key] = value
+        for key, value in pending.items():
+            setattr(self, key, value)
+
+
+def _reject_constant(_: str) -> Any:
+    raise ImportValidationError("invalid_number", "json", "non-finite numbers are unsupported")
+
+
+def _unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ImportValidationError(
+                "duplicate_key", "json", "duplicate object keys are ambiguous"
+            )
+        result[key] = value
+    return result
+
+
+def _preflight_depth(data: bytes, limit: int) -> None:
+    depth = 0
+    quoted = escaped = False
+    for char in data:
+        if quoted:
+            if escaped:
+                escaped = False
+            elif char == 92:
+                escaped = True
+            elif char == 34:
+                quoted = False
+        elif char == 34:
+            quoted = True
+        elif char in (91, 123):
+            depth += 1
+            if depth > limit:
+                raise ImportValidationError(
+                    "limit_exceeded", "json.depth", "nesting limit exceeded"
+                )
+        elif char in (93, 125):
+            depth -= 1
+
+
+def validate_json_tree(value: Any, limits: ImportLimits = ImportLimits()) -> None:
+    """Check Python inputs too; no implicit tuple/key coercion or non-finite JSON."""
+
+    pending = [(value, 0)]
+    count = 0
+    while pending:
+        node, depth = pending.pop()
+        count += 1
+        if count > limits.max_nodes:
+            raise ImportValidationError("limit_exceeded", "json.nodes", "node limit exceeded")
+        if type(node) in {dict, list}:
+            if depth + 1 > limits.max_depth:
+                raise ImportValidationError(
+                    "limit_exceeded", "json.depth", "nesting limit exceeded"
+                )
+            if len(node) + len(pending) + count > limits.max_nodes:
+                raise ImportValidationError("limit_exceeded", "json.nodes", "node limit exceeded")
+            if isinstance(node, dict):
+                if any(type(key) is not str for key in node):
+                    raise ImportValidationError(
+                        "invalid_json", "json", "object keys must be strings"
+                    )
+                for key in node:
+                    try:
+                        key.encode("utf-8")
+                    except UnicodeError as exc:
+                        raise ImportValidationError(
+                            "invalid_json", "json", "strings must be valid UTF-8"
+                        ) from exc
+                pending.extend((item, depth + 1) for item in node.values())
+            else:
+                pending.extend((item, depth + 1) for item in node)
+        elif type(node) is float:
+            if not math.isfinite(node):
+                raise ImportValidationError("invalid_number", "json", "numbers must be finite")
+        elif type(node) is int:
+            if (
+                node.bit_length() > limits.max_number_chars * 4
+                or len(str(node)) > limits.max_number_chars
+            ):
+                raise ImportValidationError(
+                    "limit_exceeded", "json.number", "number length exceeded"
+                )
+        elif type(node) is str:
+            try:
+                node.encode("utf-8")
+            except UnicodeError as exc:
+                raise ImportValidationError(
+                    "invalid_json", "json", "strings must be valid UTF-8"
+                ) from exc
+        elif node is not None and type(node) not in {str, bool}:
+            raise ImportValidationError("invalid_json", "json", "unsupported JSON value")
+
+
+def parse_json_bytes(data: bytes, limits: ImportLimits = ImportLimits()) -> Any:
+    if len(data) > limits.max_json_bytes:
+        raise ImportValidationError("limit_exceeded", "json.bytes", "JSON byte limit exceeded")
+    _preflight_depth(data, limits.max_depth)
+
+    def number(text: str, convert: Any) -> Any:
+        if len(text) > limits.max_number_chars:
+            raise ImportValidationError("limit_exceeded", "json.number", "number length exceeded")
+        return convert(text)
+
+    try:
+        value = json.loads(
+            data.decode("utf-8"),
+            object_pairs_hook=_unique_object,
+            parse_constant=_reject_constant,
+            parse_int=lambda text: number(text, int),
+            parse_float=lambda text: number(text, float),
+        )
+    except (UnicodeError, json.JSONDecodeError, RecursionError) as exc:
+        raise ImportValidationError("invalid_json", "json", "invalid UTF-8 JSON document") from exc
+    validate_json_tree(value, limits)
+    return value
+
+
+_DEVICE = re.compile(r"^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\.|$)", re.IGNORECASE)
+
+
+def relative_reference(value: Any, limits: ImportLimits = ImportLimits()) -> str:
+    """Require normalized POSIX relative names portable to Windows and Unix."""
+
+    try:
+        length = len(value.encode("utf-8")) if isinstance(value, str) else 0
+    except UnicodeError as exc:
+        raise ImportValidationError("unsafe_path", "reference", "path must be valid UTF-8") from exc
+    if not isinstance(value, str) or not value or length > 4096:
+        raise ImportValidationError("unsafe_path", "reference", "must be a bounded relative path")
+    if (
+        "\\" in value
+        or ":" in value
+        or any(ord(char) < 32 or char in '<>"|?*' for char in value)
+        or PureWindowsPath(value).drive
+        or value.startswith("/")
+    ):
+        raise ImportValidationError(
+            "unsafe_path", "reference", "absolute, remote or ambiguous path"
+        )
+    parts = value.split("/")
+    if len(parts) > limits.max_path_depth:
+        raise ImportValidationError("limit_exceeded", "reference.depth", "path depth exceeded")
+    if any(
+        part in {"", ".", ".."} or part.endswith((" ", ".")) or _DEVICE.match(part)
+        for part in parts
+    ):
+        raise ImportValidationError(
+            "unsafe_path", "reference", "path is not normalized or portable"
+        )
+    return value
+
+
+def safe_artifact_path(
+    root: str | Path, reference: str, limits: ImportLimits = ImportLimits()
+) -> Path:
+    reference = relative_reference(reference, limits)
+    try:
+        base = Path(root).resolve(strict=True)
+        if not base.is_dir():
+            raise ImportValidationError("invalid_root", "root", "artifact root must be a directory")
+        candidate = base
+        for part in reference.split("/"):
+            candidate = candidate / part
+            if indirect_path(candidate):
+                raise ImportValidationError(
+                    "unsafe_path", "reference", "symlinks and junctions are unsupported"
+                )
+        resolved = candidate.resolve(strict=True)
+        if not resolved.is_relative_to(base):
+            raise ImportValidationError("unsafe_path", "reference", "path leaves artifact root")
+        if not stat.S_ISREG(resolved.stat().st_mode):
+            raise ImportValidationError(
+                "invalid_artifact", "reference", "artifact must be a regular file"
+            )
+        return resolved
+    except OSError as exc:
+        raise ImportValidationError(
+            "missing_artifact", "reference", "artifact is unavailable"
+        ) from exc
+    except RuntimeError as exc:
+        raise ImportValidationError(
+            "unsafe_path", "reference", "unresolvable artifact path"
+        ) from exc
+
+
+def indirect_path(path: Path) -> bool:
+    """Recognize symlinks/reparse entries on Python 3.10 as well as newer APIs."""
+    reparse = getattr(path.lstat(), "st_file_attributes", 0) & getattr(
+        stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400
+    )
+    return bool(path.is_symlink() or reparse or getattr(path, "is_junction", lambda: False)())
+
+
+@dataclass(frozen=True)
+class JsonArtifact:
+    reference: str
+    artifact_sha256: str
+    byte_count: int
+    payload: Any
+
+
+def load_json_artifact(
+    root: str | Path,
+    reference: str,
+    *,
+    limits: ImportLimits = ImportLimits(),
+    budget: ImportBudget | None = None,
+) -> JsonArtifact:
+    if budget is not None and budget.limits != limits:
+        raise ImportValidationError(
+            "invalid_limit", "budget", "budget and parser limits must match"
+        )
+    path = safe_artifact_path(root, reference, limits)
+    bound = limits.max_json_bytes
+    if budget is not None:
+        if budget.records >= limits.max_records:
+            raise ImportValidationError("limit_exceeded", "records", "import budget exceeded")
+        bound = min(bound, limits.max_total_bytes - budget.total_bytes)
+    try:
+        with path.open("rb") as stream:
+            data = stream.read(bound + 1)
+        # Recheck static references before accepting data. This is not an OS
+        # sandbox or an atomic defense against concurrent filesystem mutation.
+        if safe_artifact_path(root, reference, limits) != path:
+            raise ImportValidationError(
+                "unsafe_path", "reference", "artifact path changed while reading"
+            )
+    except OSError as exc:
+        raise ImportValidationError(
+            "invalid_artifact", "reference", "artifact could not be read"
+        ) from exc
+    if budget is not None:
+        budget.consume(total_bytes=len(data), records=1)
+    digest = sha256(data).hexdigest()
+    try:
+        payload = parse_json_bytes(data, limits)
+    except ImportValidationError as exc:
+        if exc.code != "limit_exceeded":
+            exc.artifact_reference = reference
+            exc.artifact_sha256 = digest
+            exc.byte_count = len(data)
+        raise
+    return JsonArtifact(reference, digest, len(data), payload)

agentloop/intervention_service.py

@@ -0,0 +1,110 @@
+"""Create interventions from project-scoped stored evidence without re-diagnosis."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import fields
+from typing import Any
+
+from agentloop.interventions import (
+    InterventionReferenceError,
+    InterventionValidationError,
+    build_intervention,
+)
+from agentloop.quality import build_quality_report, validate_quality_fixtures
+from agentloop.replay import ReplayGates
+
+
+def parse_replay_gates(value: Any) -> ReplayGates:
+    if not isinstance(value, dict):
+        raise InterventionValidationError("gates must be an object")
+    defaults = ReplayGates()
+    names = {field.name for field in fields(defaults)}
+    if set(value) - names:
+        raise InterventionValidationError("unknown replay gate option")
+    for key, item in value.items():
+        if key.startswith("require_"):
+            if type(item) is not bool:
+                raise InterventionValidationError(f"{key} must be a boolean")
+        elif item is None and key == "min_quality_score":
+            continue
+        elif (
+            isinstance(item, bool)
+            or not isinstance(item, int | float)
+            or not math.isfinite(item)
+            or item < 0
+        ):
+            raise InterventionValidationError(f"{key} must be a finite nonnegative number")
+        elif key == "min_quality_score" and item > 1:
+            raise InterventionValidationError("min_quality_score must be between 0 and 1")
+    return ReplayGates(**value)
+
+
+def create_stored_intervention(
+    db: Any, request: dict[str, Any], project_id: str = "default"
+) -> dict[str, Any]:
+    allowed = {
+        "baseline_run_id",
+        "candidate_run_id",
+        "target_finding_ids",
+        "intervention_type",
+        "configuration",
+        "metadata",
+        "gates",
+        "quality_fixtures",
+    }
+    if not isinstance(request, dict) or set(request) - allowed:
+        raise InterventionValidationError("invalid intervention request fields")
+    for key in ("baseline_run_id", "candidate_run_id", "intervention_type"):
+        if not isinstance(request.get(key), str) or not request[key].strip():
+            raise InterventionValidationError(f"{key} must be a nonempty string")
+    targets = request.get("target_finding_ids")
+    if (
+        not isinstance(targets, list)
+        or not targets
+        or any(not isinstance(item, str) or not item for item in targets)
+    ):
+        raise InterventionValidationError("target_finding_ids must contain at least one ID")
+    gates = parse_replay_gates(request.get("gates", {}))
+    baseline = db.get_trace(request["baseline_run_id"], project_id=project_id)
+    candidate = db.get_trace(request["candidate_run_id"], project_id=project_id)
+    if baseline is None or candidate is None:
+        raise InterventionReferenceError("baseline or candidate trace not found")
+    snapshots = [
+        db.get_finding_snapshot(baseline.run_id, target, project_id=project_id)
+        for target in sorted(set(targets))
+    ]
+    if any(snapshot is None for snapshot in snapshots):
+        raise InterventionReferenceError("target baseline finding not found")
+    fixtures = request.get("quality_fixtures")
+    if fixtures is not None:
+        validate_quality_fixtures(fixtures)
+        if any(
+            str(fixture.get("scorer", {}).get("type", "")).strip().lower() == "custom"
+            for fixture in fixtures
+        ):
+            raise InterventionValidationError(
+                "custom Python scorers are not accepted for stored intervention requests"
+            )
+    quality = (
+        None
+        if fixtures is None
+        else build_quality_report(
+            fixtures,
+            baseline_trace=baseline,
+            candidate_trace=candidate,
+            min_score=gates.min_quality_score,
+        )
+    )
+    record = build_intervention(
+        baseline,
+        candidate,
+        target_finding_ids=targets,
+        intervention_type=request["intervention_type"],
+        configuration=request.get("configuration", {}),
+        metadata=request.get("metadata", {}),
+        diagnosis={"run_id": baseline.run_id, "findings": snapshots},
+        gates=gates,
+        quality_report=quality,
+    )
+    return db.save_intervention(record, project_id=project_id)

agentloop/intervention_store.py

@@ -0,0 +1,118 @@
+"""Shared SQLite/Postgres intervention contract; dialect differences stay local."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from agentloop.interventions import (
+    InterventionConflictError,
+    InterventionRecord,
+    InterventionReferenceError,
+    canonical_json,
+    trace_fingerprint,
+)
+from agentloop.tracer import AgentTrace
+
+
+class InterventionStoreMixin:
+    _postgres_interventions = False
+
+    def _intervention_sql(self, sql: str) -> str:
+        return sql.replace("?", "%s") if self._postgres_interventions else sql
+
+    def get_finding_snapshot(
+        self, run_id: str, finding_id: str, project_id: str = "default"
+    ) -> dict[str, Any] | None:
+        self.init()
+        with self._connect() as conn:
+            row = conn.execute(
+                self._intervention_sql(
+                    "SELECT payload_json FROM trace_findings WHERE project_id = ? AND run_id = ? AND finding_id = ?"
+                ),
+                (project_id, run_id, finding_id),
+            ).fetchone()
+        if row is None:
+            return None
+        return json.loads(row[0]) if isinstance(row[0], str) else row[0]
+
+    def get_intervention(
+        self, intervention_id: str, project_id: str = "default"
+    ) -> dict[str, Any] | None:
+        self.init()
+        with self._connect() as conn:
+            row = conn.execute(
+                self._intervention_sql(
+                    "SELECT payload_json FROM interventions WHERE project_id = ? AND intervention_id = ?"
+                ),
+                (project_id, intervention_id),
+            ).fetchone()
+        return None if row is None else json.loads(row[0])
+
+    def save_intervention(
+        self, record: InterventionRecord | dict[str, Any], project_id: str = "default"
+    ) -> dict[str, Any]:
+        validated = InterventionRecord.from_dict(
+            record.to_dict() if isinstance(record, InterventionRecord) else record
+        )
+        payload = validated.to_dict()
+        serialized = canonical_json(payload)
+        self.init()
+        with self._connect() as conn:
+            if not self._postgres_interventions:
+                conn.execute("BEGIN IMMEDIATE")
+            lookup = self._intervention_sql(
+                "SELECT payload_json FROM interventions WHERE project_id = ? AND intervention_id = ?"
+            )
+            identity = (project_id, validated.intervention_id)
+            existing = conn.execute(lookup, identity).fetchone()
+            if existing is not None:
+                if canonical_json(json.loads(existing[0])) != serialized:
+                    raise InterventionConflictError(
+                        "intervention identity already has different evidence"
+                    )
+                return json.loads(existing[0])
+            for condition in ("baseline", "candidate"):
+                query = "SELECT payload_json FROM traces WHERE project_id = ? AND run_id = ?"
+                if self._postgres_interventions:
+                    query += " FOR SHARE"
+                row = conn.execute(
+                    self._intervention_sql(query), (project_id, payload[f"{condition}_run_id"])
+                ).fetchone()
+                if row is None:
+                    raise InterventionReferenceError("baseline or candidate trace not found")
+                native = json.loads(row[0]) if isinstance(row[0], str) else row[0]
+                if (
+                    trace_fingerprint(AgentTrace.from_dict(native))
+                    != payload["trace_fingerprints"][condition]
+                ):
+                    raise InterventionConflictError(
+                        "stored trace differs from the intervention's source trace"
+                    )
+            for finding_id in payload["target_finding_ids"]:
+                query = "SELECT finding_id FROM trace_findings WHERE project_id = ? AND run_id = ? AND finding_id = ?"
+                if self._postgres_interventions:
+                    query += " FOR SHARE"
+                if (
+                    conn.execute(
+                        self._intervention_sql(query),
+                        (project_id, payload["baseline_run_id"], finding_id),
+                    ).fetchone()
+                    is None
+                ):
+                    raise InterventionReferenceError("target baseline finding not found")
+            conn.execute(
+                self._intervention_sql(
+                    "INSERT INTO interventions(project_id, intervention_id, baseline_run_id, candidate_run_id, payload_json) "
+                    "VALUES (?, ?, ?, ?, ?) ON CONFLICT(project_id, intervention_id) DO NOTHING"
+                ),
+                (*identity, payload["baseline_run_id"], payload["candidate_run_id"], serialized),
+            )
+            # Concurrent Postgres writers may reach INSERT together. Only an
+            # identical winner satisfies the retry contract.
+            stored = conn.execute(lookup, identity).fetchone()
+            if canonical_json(json.loads(stored[0])) != serialized:
+                raise InterventionConflictError(
+                    "intervention identity already has different evidence"
+                )
+            return json.loads(stored[0])