failproofai 1.0.11 → 1.0.12-beta.1

package/.next/standalone/fp-cloud-cli/fp_cli/enforcement.py

@@ -28,20 +28,38 @@ re-reads rather than reporting a success that erased somebody.
 """
 from __future__ import annotations
 
+import json
 import re
 import sys
-from dataclasses import dataclass
-from typing import Dict, Iterable, List, Optional, Sequence, Tuple
+from dataclasses import dataclass, replace as dataclass_replace
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
 
 from .errors import ApiError
 from .models import PolicyRef, PolicyVersion
 
 VALID_EFFECTS = ("enforce", "observe")
 
+#: What a policy version carries: JavaScript (`regex`), Jev checks (`jev`), or
+#: JavaScript reviewable by its own Jev checks (`both`).
+VALID_KINDS = ("regex", "jev", "both")
+
+#: The Jev modes a deployment may set. `local` stops FailproofAI Cloud
+#: overriding the machine's own mode (the server stores it as no value).
+JEV_MODES = ("off", "observe", "enforce", "local")
+
+#: The server's (and the machine's) cap on Jev declarations per policy version.
+MAX_JEV_DECLARATIONS = 24
+AGENT_INTEGRATIONS = frozenset({
+    "claude", "codex", "copilot", "cursor", "opencode", "pi",
+    "hermes", "openclaw", "factory", "devin", "antigravity", "goose",
+})
+AGENT_ID = re.compile(r"^agt_[0-9a-f]{16,32}$")
+
 #: `id`, `id@3`, `id:observe`, `id@3:observe`. The id charset mirrors the
 #: server's `safe_identifier`, so a ref this accepts is one the server will too
 #: — a rejection should come from the policy not existing, not from parsing.
 _REF = re.compile(r"^(?P<id>[A-Za-z0-9._-]{1,128})(?:@(?P<version>\d+))?(?:[:](?P<effect>[a-z]+))?$")
+_POLICY_ID = re.compile(r"^[A-Za-z0-9._-]{1,128}$")
 
 
 class RefError(ValueError):
@@ -102,13 +120,34 @@ class DeployPlan:
     removed: List[PolicyRef]
     changed: List[Tuple[PolicyRef, PolicyRef]]
     unchanged: List[PolicyRef]
+    #: `--jev-mode` as given (`off|observe|enforce|local`), or None when the
+    #: command said nothing about Jev — which the server reads as "keep it".
+    jev_mode: Optional[str] = None
+    #: The mode FailproofAI Cloud sets on the machine now (None = local).
+    jev_mode_before: Optional[str] = None
+
+    @property
+    def jev_mode_after(self) -> Optional[str]:
+        """What the machine's Cloud-set mode will be (None = local)."""
+        if self.jev_mode is None:
+            return self.jev_mode_before
+        return None if self.jev_mode == "local" else self.jev_mode
+
+    @property
+    def jev_mode_changes(self) -> bool:
+        return self.jev_mode is not None and self.jev_mode_after != self.jev_mode_before
+
+    @property
+    def set_changes(self) -> bool:
+        """Whether the POLICY SET changes — anything added, removed or moved."""
+        return bool(self.added or self.removed or self.changed)
 
     @property
     def is_noop(self) -> bool:
-        return not (self.added or self.removed or self.changed)
+        return not (self.set_changes or self.jev_mode_changes)
 
     def to_dict(self) -> Dict[str, object]:
-        return {
+        out: Dict[str, object] = {
             "machineId": self.machine_id,
             "base": self.base,
             "result": [p.to_dict() for p in self.result],
@@ -118,6 +157,14 @@ class DeployPlan:
             "unchanged": [p.to_dict() for p in self.unchanged],
             "noop": self.is_noop,
         }
+        if self.jev_mode is not None:
+            # `local` on both sides: the wire word, not the stored NULL.
+            out["jevMode"] = {
+                "from": self.jev_mode_before or "local",
+                "to": self.jev_mode_after or "local",
+                "changed": self.jev_mode_changes,
+            }
+        return out
 
 
 def latest_versions(policies: Iterable[PolicyVersion]) -> Dict[str, int]:
@@ -174,7 +221,10 @@ def resolve_ref(
         )
     if effect is None:
         effect = existing.effect if existing else "enforce"
-    return PolicyRef(id=pid, version=version, effect=effect)
+    return PolicyRef(
+        id=pid, version=version, effect=effect,
+        agent_targets=existing.agent_targets if existing else None,
+    )
 
 
 def plan_deploy(
@@ -187,13 +237,28 @@ def plan_deploy(
     replace: Optional[Sequence[str]] = None,
     latest: Optional[Dict[str, int]] = None,
     disabled: Optional[set] = None,
+    jev_mode: Optional[str] = None,
+    current_jev_mode: Optional[str] = None,
+    kinds: Optional[Dict[Tuple[str, int], str]] = None,
+    targets: Sequence[str] = (),
+    all_agents: Sequence[str] = (),
 ) -> DeployPlan:
     """Compute the full resulting set, plus the diff to show before writing.
 
     `replace` (`--set`) is exclusive with `add`/`remove`: mixing "these exactly"
     with "these as well" has no single obvious reading, and guessing one would
     be guessing about somebody's fleet.
+
+    `jev_mode` is `--jev-mode`; `current_jev_mode` what Cloud sets now (None =
+    local). `kinds` maps `(id, version)` to the version's kind, so an `observe`
+    effect on a Jev-only version — which the server refuses, because a Jev
+    rollout is observed through the Jev MODE — is refused here, before a plan is
+    drawn and confirmed for a write that cannot happen.
     """
+    if jev_mode is not None and jev_mode not in JEV_MODES:
+        raise RefUsageError(
+            f"--jev-mode {jev_mode!r} is not one of {', '.join(JEV_MODES)}"
+        )
     latest = latest or {}
     current_list = list(current or [])
     current_map = {p.id: p for p in current_list}
@@ -220,13 +285,48 @@ def plan_deploy(
             ref = resolve_ref(token, latest=latest, current=current_map, disabled=disabled)
             result_map[ref.id] = ref
 
+    grouped: Dict[str, List[Dict[str, str]]] = {}
+    for token in targets:
+        if "=" not in token:
+            raise RefUsageError(f"--target {token!r} must be POLICY=INTEGRATION[/agt_ID]")
+        pid, selector = token.split("=", 1)
+        if not _POLICY_ID.fullmatch(pid):
+            raise RefUsageError(f"--target policy id {pid!r} is invalid")
+        integration, _, instance_id = selector.partition("/")
+        if integration not in AGENT_INTEGRATIONS or ("/" in selector and not AGENT_ID.fullmatch(instance_id)):
+            raise RefUsageError(f"--target {token!r} has an unknown integration or invalid profile ID")
+        entry = {"integration": integration}
+        if instance_id:
+            entry["instanceId"] = instance_id
+        collection = grouped.setdefault(pid, [])
+        if entry in collection or len(collection) == 32:
+            raise RefUsageError("--target has a duplicate selector or more than 32 selectors for a policy")
+        collection.append(entry)
+    clears = set(all_agents)
+    if clears.intersection(grouped):
+        raise RefUsageError("--all-agents and --target cannot name the same policy")
+    for pid in clears:
+        if not _POLICY_ID.fullmatch(pid):
+            raise RefUsageError(f"--all-agents policy id {pid!r} is invalid")
+    for pid in grouped.keys() | clears:
+        if pid not in result_map:
+            raise RefUsageError(f"{pid!r} is not in the resulting set — add or keep it before targeting")
+        result_map[pid] = dataclass_replace(result_map[pid], agent_targets=grouped.get(pid))
+
     result = sorted(result_map.values(), key=lambda p: p.id)
+    for ref in result:
+        if ref.effect == "observe" and (kinds or {}).get((ref.id, ref.version)) == "jev":
+            raise RefUsageError(
+                f"{ref.id}@{ref.version} is a Jev policy, and an effect does not apply to Jev "
+                "checks — deploy it as enforce and use --jev-mode observe to watch Jev without "
+                "it deciding anything"
+            )
     added, removed, changed, unchanged = [], [], [], []
     for pid, ref in sorted(result_map.items()):
         was = current_map.get(pid)
         if was is None:
             added.append(ref)
-        elif (was.version, was.effect) != (ref.version, ref.effect):
+        elif (was.version, was.effect, was.agent_targets) != (ref.version, ref.effect, ref.agent_targets):
             changed.append((was, ref))
         else:
             unchanged.append(ref)
@@ -242,9 +342,73 @@ def plan_deploy(
         removed=removed,
         changed=changed,
         unchanged=unchanged,
+        jev_mode=jev_mode,
+        jev_mode_before=current_jev_mode,
     )
 
 
+def jev_mode_after(mode: str) -> Optional[str]:
+    """What a `--jev-mode`/`jev-mode` word leaves stored: `local` is None (Cloud stops overriding)."""
+    return None if mode == "local" else mode
+
+
+def version_kinds(policies: Iterable[PolicyVersion]) -> Dict[Tuple[str, int], str]:
+    """`{(id, version): kind}` for every published version."""
+    return {(p.id, p.version): p.kind for p in policies}
+
+
+def resolve_kind(kind: Optional[str], *, has_source: bool, has_semantic: bool) -> str:
+    """The kind a publish is, checked against what it was given.
+
+    Explicit wins; otherwise it follows from the inputs — JavaScript alone is
+    `regex` (what `publish` has always done), declarations alone `jev`, both
+    together `both`. A kind that contradicts its inputs is a usage error: a
+    `jev` policy has no JavaScript, and `regex` has no declarations.
+    """
+    if kind is None:
+        kind = "both" if (has_source and has_semantic) else ("jev" if has_semantic else "regex")
+    if kind not in VALID_KINDS:
+        raise RefUsageError(f"--kind {kind!r} is not one of {', '.join(VALID_KINDS)}")
+    if kind == "regex" and has_semantic:
+        raise RefUsageError("--kind regex takes no --semantic; use --kind both for JavaScript plus Jev checks")
+    if kind == "jev" and has_source:
+        raise RefUsageError("--kind jev takes no JavaScript source; use --kind both for JavaScript plus Jev checks")
+    if kind in ("jev", "both") and not has_semantic:
+        raise RefUsageError(f"--kind {kind} needs --semantic <file.json> with its Jev declarations")
+    return kind
+
+
+def parse_semantic(text: str, *, what: str = "--semantic") -> List[Any]:
+    """The Jev declarations in a `--semantic` file: a JSON array of declaration
+    objects (a `{"semantic": [...]}` wrapper is accepted too).
+
+    Deliberately a SHAPE check only — 1 to 24 objects, each with a name. What a
+    declaration may say (modes, probes, caps, reserved names) is checked by the
+    server, and authoritatively by each machine's own parser; a third copy of
+    those rules here is a third thing to drift. The server's refusal names the
+    declaration and the rule.
+    """
+    try:
+        value = json.loads(text)
+    except ValueError as exc:
+        raise RefUsageError(f"{what} is not valid JSON: {exc}")
+    if isinstance(value, dict) and isinstance(value.get("semantic"), list):
+        value = value["semantic"]
+    if not isinstance(value, list):
+        raise RefUsageError(f"{what} must be a JSON array of Jev declarations")
+    if not value:
+        raise RefUsageError(f"{what} holds no Jev declarations")
+    if len(value) > MAX_JEV_DECLARATIONS:
+        raise RefUsageError(
+            f"{what} holds {len(value)} Jev declarations; a policy version carries at most "
+            f"{MAX_JEV_DECLARATIONS}"
+        )
+    for i, entry in enumerate(value):
+        if not isinstance(entry, dict) or not isinstance(entry.get("name"), str) or not entry["name"]:
+            raise RefUsageError(f"{what} declaration #{i} is not an object with a name")
+    return value
+
+
 def check_race(base: Optional[int], returned: int) -> None:
     """Raise when a deploy landed on top of somebody else's.
 

package/.next/standalone/fp-cloud-cli/fp_cli/models.py

@@ -724,7 +724,17 @@ class AuditFinding:
 
 @dataclass
 class PolicyVersion:
-    """One published version of a policy. Versions are minted, never edited."""
+    """One published version of a policy. Versions are minted, never edited.
+
+    ``kind`` is what the version carries: ``regex`` (JavaScript only — every
+    version published before kinds existed), ``jev`` (Jev checks only, no
+    JavaScript) or ``both`` (JavaScript whose verdict its own Jev checks may
+    clear). ``semantic`` is the list of Jev declarations for ``jev``/``both``.
+    ``authority``/``reviewed_by`` are DERIVED by the server from the kind and
+    never sent by a client. ``jev_chars`` is what its Jev checks take of a
+    machine's Jev question budget, measured by the server the way the machine
+    measures it; ``None`` for ``regex``.
+    """
 
     id: str
     version: int
@@ -735,9 +745,18 @@ class PolicyVersion:
     created_by: Optional[str]
     disabled: bool
     archived: bool
+    kind: str = "regex"
+    semantic: Optional[List[Any]] = None
+    semantic_sha256: Optional[str] = None
+    authority: Optional[str] = None
+    reviewed_by: Optional[List[str]] = None
+    jev_chars: Optional[int] = None
 
     @classmethod
     def from_dict(cls, d: Dict[str, Any]) -> "PolicyVersion":
+        semantic = d.get("semantic")
+        reviewed = d.get("reviewedBy", d.get("reviewed_by"))
+        chars = d.get("jevChars", d.get("jev_chars"))
         return cls(
             id=str(d.get("id", "")),
             version=_as_int(d.get("version"), 0),
@@ -748,18 +767,46 @@ class PolicyVersion:
             created_by=d.get("createdBy", d.get("created_by")),
             disabled=bool(d.get("disabled", False)),
             archived=bool(d.get("archived", False)),
+            # A server that predates kinds sends none, and everything it has is
+            # JavaScript — `regex` is not a guess, it is the only thing it had.
+            kind=str(d.get("kind") or "regex"),
+            semantic=semantic if isinstance(semantic, list) else None,
+            semantic_sha256=d.get("semanticSha256", d.get("semantic_sha256")),
+            authority=d.get("authority"),
+            reviewed_by=[str(n) for n in reviewed] if isinstance(reviewed, list) else None,
+            jev_chars=chars if isinstance(chars, int) and not isinstance(chars, bool) else None,
         )
 
+    @property
+    def jev_names(self) -> List[str]:
+        """The names of this version's Jev checks, in declared order."""
+        return [
+            str(entry["name"])
+            for entry in (self.semantic or [])
+            if isinstance(entry, dict) and isinstance(entry.get("name"), str)
+        ]
+
     def to_dict(self) -> Dict[str, Any]:
         """The server's own shape. `vars()` would leak Python snake_case into a
         contract that is camelCase everywhere else, which is a difference a
         harness discovers at runtime rather than in review."""
-        return {
+        out: Dict[str, Any] = {
             "id": self.id, "version": self.version, "description": self.description,
             "sha256": self.sha256, "source": self.source, "createdAt": self.created_at,
             "createdBy": self.created_by, "disabled": self.disabled,
-            "archived": self.archived,
+            "archived": self.archived, "kind": self.kind,
         }
+        if self.semantic is not None:
+            out["semantic"] = self.semantic
+        if self.semantic_sha256:
+            out["semanticSha256"] = self.semantic_sha256
+        if self.authority:
+            out["authority"] = self.authority
+        if self.reviewed_by is not None:
+            out["reviewedBy"] = self.reviewed_by
+        if self.jev_chars is not None:
+            out["jevChars"] = self.jev_chars
+        return out
 
 
 @dataclass
@@ -774,6 +821,9 @@ class PolicyRef:
     id: str
     version: int
     effect: str = "enforce"
+    #: None means every agent; a nonempty selector list narrows this
+    #: machine's assignment, never the immutable published policy version.
+    agent_targets: Optional[List[Dict[str, str]]] = None
 
     @classmethod
     def from_dict(cls, d: Dict[str, Any]) -> "PolicyRef":
@@ -781,14 +831,23 @@ class PolicyRef:
             id=str(d.get("id", "")),
             version=_as_int(d.get("version"), 0),
             effect=str(d.get("effect") or "enforce"),
+            agent_targets=[dict(target) for target in d["agentTargets"]]
+            if isinstance(d.get("agentTargets"), list) else None,
         )
 
     def to_dict(self) -> Dict[str, Any]:
-        return {"id": self.id, "version": self.version, "effect": self.effect}
+        out: Dict[str, Any] = {"id": self.id, "version": self.version, "effect": self.effect}
+        if self.agent_targets is not None:
+            out["agentTargets"] = self.agent_targets
+        return out
 
     @property
     def label(self) -> str:
-        return f"{self.id}@{self.version}:{self.effect}"
+        scope = "" if not self.agent_targets else " → " + ", ".join(
+            f"{t['integration']}/{t['instanceId']}" if t.get("instanceId") else f"all {t['integration']}"
+            for t in self.agent_targets
+        )
+        return f"{self.id}@{self.version}:{self.effect}{scope}"
 
 
 @dataclass
@@ -806,6 +865,9 @@ class Deployment:
     policies: List[PolicyRef]
     updated_at: str
     updated_by: Optional[str]
+    #: The Jev mode FailproofAI Cloud sets on this machine (`off|observe|enforce`),
+    #: or None when Cloud does not override the machine's own (`local`).
+    jev_mode: Optional[str] = None
 
     @classmethod
     def from_dict(cls, d: Dict[str, Any]) -> "Deployment":
@@ -815,14 +877,18 @@ class Deployment:
             policies=[PolicyRef.from_dict(p) for p in (d.get("policies") or [])],
             updated_at=str(d.get("updatedAt", d.get("updated_at", "")) or ""),
             updated_by=d.get("updatedBy", d.get("updated_by")),
+            jev_mode=d.get("jevMode", d.get("jev_mode")) or None,
         )
 
     def to_dict(self) -> Dict[str, Any]:
-        return {
+        out: Dict[str, Any] = {
             "machineId": self.machine_id, "deployment": self.deployment,
             "policies": [p.to_dict() for p in self.policies],
             "updatedAt": self.updated_at, "updatedBy": self.updated_by,
         }
+        if self.jev_mode:
+            out["jevMode"] = self.jev_mode
+        return out
 
 
 @dataclass
@@ -851,6 +917,13 @@ class Machine:
     deployed: bool
     policy_count: int
     event_count: int
+    #: What the machine last reported it could not apply — `[{id, version, kind,
+    #: message}]` — or None when it has never reported (an empty list means it
+    #: reported and all is well).
+    policy_errors: Optional[List[Dict[str, Any]]] = None
+    policy_errors_at: Optional[Any] = None
+    #: The Jev mode FailproofAI Cloud sets on this machine, or None (`local`).
+    jev_mode: Optional[str] = None
 
     @classmethod
     def from_dict(cls, d: Dict[str, Any]) -> "Machine":
@@ -858,6 +931,8 @@ class Machine:
             v = d.get(key)
             return int(v) if isinstance(v, (int, float)) else None
 
+        errors = d.get("policyErrors", d.get("policy_errors"))
+
         return cls(
             machine_id=str(d.get("machineId", d.get("machine_id", "")) or ""),
             label=d.get("label"),
@@ -870,6 +945,9 @@ class Machine:
             deployed=bool(d.get("deployed", False)),
             policy_count=_as_int(d.get("policyCount"), 0),
             event_count=_as_int(d.get("eventCount"), 0),
+            policy_errors=[e for e in errors if isinstance(e, dict)] if isinstance(errors, list) else None,
+            policy_errors_at=d.get("policyErrorsAt", d.get("policy_errors_at")),
+            jev_mode=d.get("jevMode", d.get("jev_mode")) or None,
         )
 
     @property
@@ -892,6 +970,11 @@ class Machine:
             "appliedAt": self.applied_at, "deployed": self.deployed,
             "policyCount": self.policy_count, "eventCount": self.event_count,
             "drifted": self.drifted,
+            # Emitted only when the server sent them, so a server that predates
+            # them reads exactly as it always did.
+            **({"policyErrors": self.policy_errors} if self.policy_errors is not None else {}),
+            **({"policyErrorsAt": self.policy_errors_at} if self.policy_errors_at is not None else {}),
+            **({"jevMode": self.jev_mode} if self.jev_mode else {}),
         }
 
     @property