failproofai 1.0.11 → 1.0.12-beta.1

package/.next/standalone/fp-cloud-cli/CHANGELOG.md

@@ -4,6 +4,36 @@
 
 ### Added
 
+- `fp fleet deploy --target POLICY=INTEGRATION[/agt_ID]` scopes a machine's assignment; repeat the flag to include multiple alternatives. `--all-agents POLICY` explicitly clears its scope. Deploy plans, show, history, rollback and JSON readback retain assignment targets.
+- `fp policies publish <id> --kind regex|jev|both [--source f.mjs] [--semantic f.json]`: a
+  FailproofAI Cloud policy can carry Jev checks — `jev` (declarations only, no JavaScript) or
+  `both` (JavaScript reviewable by exactly its own checks; the server derives the authority).
+  The kind follows from what is given when `--kind` is omitted, and a kind that contradicts its
+  inputs is exit 2 before anything is sent. The positional source still works.
+- `fp fleet deploy … --jev-mode off|observe|enforce|local` sets the machine's Jev mode from
+  FailproofAI Cloud (overriding the machine's own; `local` hands it back). Omitted, the request
+  carries no `jevMode` and the mode is unchanged; `--jev-mode` alone is a valid deploy. An
+  `observe` effect on a `jev` policy is refused (exit 2) — Jev is observed through the mode.
+- `fp fleet jev-mode <machine…|--all> <mode>` changes only the Jev mode, through its own
+  route (`PUT /api/enforcement/deployments/{id}/jev-mode`), never the policy set — and
+  `fp fleet deploy --jev-mode` with no change to the set now uses it too. A deploy is a full
+  replace of the set the CLI read, which leaves out disabled policies' assignments, so a
+  mode change sent as a deploy deleted them and reverted concurrent edits.
+- `fp fleet rollback` says which Jev mode it restores (`jev mode <now> → <then>`, and
+  `jevModeBefore` in `--json`); `fp fleet history` shows each generation's Jev mode and marks a
+  mode-only generation as a change.
+- The `--jev-mode` and `fleet jev-mode` help says what `enforce` does: Jev's checks block calls
+  as well as clearing what they review, machine-wide (installed packs' checks included); an
+  `observe` effect on a `both` policy withholds its Jev checks.
+- The `fleet deploy`, `fleet jev-mode` and `policies publish` help says Jev checks run on
+  FailproofAI Cloud and nothing is installed on the machine, and `fleet show`/`fleet jev-mode`
+  name the reasons a machine with a mode cannot ask (`jev_unconfigured`, `transcripts_disabled`)
+  and the `jev_budget` report.
+- `fp policies list/show` print each version's kind and Jev check names (`show` also the
+  declarations); `fp fleet list/show` print the machine's Jev mode and the policy errors it
+  reported, and `--json` carries `kind`/`semantic`/`semanticSha256`/`authority`/`reviewedBy`,
+  `jevMode` and `policyErrors`/`policyErrorsAt` when the server sends them.
+
 - `jev:evaluate` is a known permission — Jev through FailproofAI Cloud, charged to the
   org's plan — so `fp keys` and `fp users` accept it instead of refusing it as unknown,
   and the `admin` preset carries it, as the server's built-in admin set now does. The
@@ -13,9 +43,15 @@
   (`events:add` + `policies:pull` + `jev:evaluate`), for an enrolled machine using Jev through
   FailproofAI Cloud. `fp keys` also refuses `jev:evaluate` without both prerequisites itself
   (exit 2, naming what is missing) instead of sending the key for the server's 422. (#833)
+- `fp policies list` and `fp policies show` print what a `jev`/`both` version's checks take of a
+  machine's Jev question budget (`jevChars`), and a deploy refused with `jev_budget_exceeded`
+  lists each Jev policy's share, largest first (the `hint` under `--json`), so the refusal says
+  which policy to leave off.
 
 ### Changed
 
+- `fp policies publish`'s refusal of Jev fields in the JavaScript now says where Jev checks go:
+  the policy's own declarations, `--kind both --semantic checks.json`.
 - `fp guardrails summary` shows how many machines run Jev in each mode, reading the summary's
   `jev.machines.observe` and `jev.machines.enforce`.
 - `fp policies publish` (and `policies compose --publish`) refuses a source carrying Jev
@@ -27,6 +63,11 @@
   same comment-aware detection, as the dashboard's publish form; the server does not read
   the source, so nothing else refuses it for `fp`. (#833)
 
+### Fixed
+
+- `fp fleet history` keeps `gen`, `when` and `jev` visible at 80 columns (rollback needs `gen`): the policy list is shortened, then dropped, and `change` wraps first.
+- `fp fleet show` and `fp fleet history` name an exact-profile target by the profile label the machine reports (`claude/.claude-work`, with the `agt_…` id kept in `show`), falling back to the bare id.
+
 ## 0.0.1 — 2026-09-22
 
 **First stable release.** `0.0.1b1` and `0.0.1b2` are the two betas behind it; the

package/.next/standalone/fp-cloud-cli/README.md

@@ -139,6 +139,48 @@ fp fleet deploy ci-runner-01 --add no-force-push
 fp guardrails summary --since 24h
 ```
 
+A policy has a **kind**: `regex` (JavaScript — the default, and what every
+earlier version is), `jev` (Jev checks only, from a JSON file of declarations —
+each exactly a failproofai pack manifest's semantic entry), or `both`
+(JavaScript whose verdict its own Jev checks may clear, deployed as one).
+Jev checks run on FailproofAI Cloud; nothing is installed on the machine.
+`--jev-mode` sets a machine's Jev mode from FailproofAI Cloud, overriding the
+machine's own; omit it and the mode is left alone. Under `observe` or `enforce`
+the machine sends each checked tool call to FailproofAI Cloud, which asks the
+checks deployed to it. The mode is the machine's, so it covers installed packs'
+checks too, and in `enforce` Jev's checks **block** calls as well as clearing
+the regex verdicts they review. `fp fleet jev-mode` changes only the mode, and
+never rewrites a machine's policy set.
+
+```bash
+fp policies publish prod-db-intent --kind jev --semantic ./checks.json
+fp policies publish no-prod-db --kind both --source ./rule.mjs --semantic ./checks.json
+fp fleet deploy ci-runner-01 --add prod-db-intent --jev-mode observe
+fp fleet jev-mode --all enforce   # the mode alone, every machine with a deployment
+fp fleet show ci-runner-01    # its Jev mode, and any policy errors it reported
+```
+
+Published policy versions do not contain agent-routing code. Each assignment
+can instead target every agent (the default), an integration including future
+profiles, or a particular profile reported by that machine. The same target
+applies to the regex and Jev parts of a `both` policy:
+
+```bash
+fp fleet deploy ci-runner-01 --add no-prod-db --target no-prod-db=hermes
+fp fleet deploy ci-runner-01 --target no-prod-db=hermes/agt_1234567890abcdef
+fp fleet deploy ci-runner-01 --all-agents no-prod-db  # explicitly remove targeting
+```
+
+Repeat `--target` for multiple alternatives on one assignment. `fp fleet
+show` and `fp fleet history` display the assigned scope; `--json` includes
+`agentTargets` on each targeted policy. A machine must report agent-scoping
+support before accepting a new target. When its identity cannot be resolved,
+a targeted policy does not match; unscoped policy remains in force.
+Newly installed shell hooks carry their settings scope. Reinstall older hooks
+to add the hint; without it, or for an integration that cannot report the
+source of multiple installed scopes, the machine reports
+`agent_scope_unresolved` rather than guessing which profile ran the call.
+
 **A deploy REPLACES a machine's whole policy set.** The server takes the full
 list and does not merge, so `fleet deploy` reads what the machine currently runs,
 applies your `--add`/`--remove`, prints the complete resulting set, and writes
@@ -256,4 +298,3 @@ working as an opt-out if it is ever switched back on. See
 cd fp-cloud-cli
 uv run --extra dev pytest
 ```
-

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

@@ -23,7 +23,7 @@ import re
 import uuid
 from dataclasses import dataclass
 from enum import Enum
-from typing import Any, Callable, Dict, Iterator, List, Optional, Sequence, Union
+from typing import Any, Callable, Dict, Iterator, List, Optional, Sequence, Tuple, Union
 
 import httpx
 
@@ -487,9 +487,39 @@ def _raise_for_status(response: httpx.Response, ctx: ClientContext) -> None:
         message or f"Request failed with status {response.status_code}.",
         status=response.status_code,
         request_id=request_id,
+        hint=_jev_budget_breakdown(response),
     )
 
 
+def _jev_budget_breakdown(response: httpx.Response) -> Optional[str]:
+    """The per-policy breakdown of a deploy's ``jev_budget_exceeded`` refusal.
+
+    The message carries only the total (``used``/``budget``); the body also lists
+    every Jev policy version the machine would carry with its question
+    characters (``policies: [{id, version, chars}]``), which is what tells an
+    operator WHICH policy to leave off. Largest first. ``None`` for any other
+    error, and for a publish refusal, which names no other policies.
+    """
+    try:
+        data = response.json()
+    except Exception:
+        return None
+    if not isinstance(data, dict) or data.get("code") != "jev_budget_exceeded":
+        return None
+    rows = [
+        (str(p.get("id", "")), p.get("version"), p["chars"])
+        for p in data.get("policies") or []
+        if isinstance(p, dict) and isinstance(p.get("chars"), int)
+    ]
+    if not rows:
+        return None
+    rows.sort(key=lambda row: -row[2])
+    parts = [f"{pid}@{version} {chars:,}" if version is not None else f"{pid} {chars:,}"
+             for pid, version, chars in rows]
+    return ("Jev question characters per policy: " + " · ".join(parts)
+            + " — deploy fewer of these Jev policies to this machine")
+
+
 def _get_json(ctx: ClientContext, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
     clean = {k: v for k, v in (params or {}).items() if v is not None}
     url = _path(ctx, path)  # chokepoint 1 of 4 for the /api -> /v1 rewrite
@@ -1643,22 +1673,43 @@ def list_policies(ctx: ClientContext) -> List[PolicyVersion]:
 
 
 def publish_policy(
-    ctx: ClientContext, policy_id: str, source: str, description: str = ""
+    ctx: ClientContext,
+    policy_id: str,
+    source: Optional[str],
+    description: str = "",
+    *,
+    kind: Optional[str] = None,
+    semantic: Optional[List[Any]] = None,
 ) -> PolicyVersion:
     """POST /api/enforcement/policies — mints a NEW VERSION; never edits in place.
 
-    Refuses Jev fields a cloud policy never reads before anything is sent, here
-    because `policies publish` and `policies compose --publish` both route through
-    it — and regardless of `--no-verify`, which only skips the syntax check.
+    ``kind`` is ``regex`` (JavaScript ``source`` only — what an omitted kind
+    means to the server), ``jev`` (Jev declarations in ``semantic``, no
+    ``source``) or ``both`` (the two together: the JavaScript is reviewable by
+    exactly its own checks). ``authority``/``reviewedBy`` are derived by the
+    server from the kind and are never sent.
+
+    Refuses Jev fields in the JAVASCRIPT before anything is sent, here because
+    `policies publish` and `policies compose --publish` both route through it —
+    and regardless of `--no-verify`, which only skips the syntax check. Jev
+    checks belong in ``semantic``, where they take effect.
     """
-    problem = cloud_publish_problem(source)
+    problem = cloud_publish_problem(source or "")
     if problem:
         raise ApiError(
             f"{policy_id} cannot be published as a cloud policy: {problem}",
-            hint=("Jev checks ship in a failproofai pack — `failproofai publish` — where "
-                  "semanticPolicies.add and authority: \"reviewable\" take effect"),
+            hint=("put Jev checks in the policy's Jev declarations — `--kind both --semantic "
+                  "checks.json` — or ship them in a failproofai pack with `failproofai publish`"),
         )
-    body = {"id": policy_id, "source": source, "description": description}
+    body: Dict[str, Any] = {"id": policy_id, "description": description}
+    # `source` is omitted for a Jev-only policy: the server takes absent (or
+    # empty) as "no JavaScript", which is what a `jev` version is.
+    if source:
+        body["source"] = source
+    if kind is not None:
+        body["kind"] = kind
+    if semantic is not None:
+        body["semantic"] = semantic
     return PolicyVersion.from_dict(_post_json(ctx, "/api/enforcement/policies", body) or {})
 
 
@@ -1681,6 +1732,29 @@ def list_machines(ctx: ClientContext) -> List[Machine]:
     return [Machine.from_dict(m) for m in items]
 
 
+def machine_agents(ctx: ClientContext, machine_id: str) -> List[Dict[str, Any]]:
+    """GET /api/enforcement/machines/{id}/agents — the agent profiles the daemon
+    last reported: `[{instanceId, integration, profileLabel, scope, ...}]`."""
+    data = _get_json(ctx, f"/api/enforcement/machines/{machine_id}/agents")
+    items = data if isinstance(data, list) else (data or {}).get("agents", [])
+    return [a for a in items if isinstance(a, dict)]
+
+
+def agent_labels(ctx: ClientContext, machine_id: str) -> Dict[str, str]:
+    """`{instanceId: profileLabel}` for one machine, or `{}` when unavailable.
+
+    Best effort on purpose: it only names the `agt_…` ids an exact-profile
+    assignment carries. A server without the roster route, or a machine that
+    never reported one, falls back to the bare id rather than failing the view.
+    """
+    try:
+        agents = machine_agents(ctx, machine_id)
+    except Exception:  # noqa: BLE001 — a missing label must never fail the read
+        return {}
+    return {str(a["instanceId"]): str(a["profileLabel"])
+            for a in agents if a.get("instanceId") and a.get("profileLabel")}
+
+
 def rename_machine(ctx: ClientContext, machine_id: str, label: str) -> Dict[str, Any]:
     """PATCH /api/enforcement/machines/{id} — a human label, not the id."""
     path = f"/api/enforcement/machines/{machine_id}"
@@ -1708,14 +1782,45 @@ def get_deployment(ctx: ClientContext, machine_id: str) -> Optional[Deployment]:
 
 
 def deploy_policies(
-    ctx: ClientContext, machine_id: str, policies: Sequence[PolicyRef]
+    ctx: ClientContext,
+    machine_id: str,
+    policies: Sequence[PolicyRef],
+    jev_mode: Optional[str] = None,
 ) -> Deployment:
-    """PUT /api/enforcement/deployments/{id} — REPLACES the machine's whole set."""
+    """PUT /api/enforcement/deployments/{id} — REPLACES the machine's whole set.
+
+    ``jev_mode`` (``off|observe|enforce|local``) is sent only when given: the
+    server reads an ABSENT ``jevMode`` as "keep the machine's current one", so a
+    deploy that says nothing about Jev never changes it. ``local`` stops
+    FailproofAI Cloud overriding the machine's own mode.
+    """
     path = f"/api/enforcement/deployments/{machine_id}"
-    body = {"policies": [p.to_dict() for p in policies]}
+    body: Dict[str, Any] = {"policies": [p.to_dict() for p in policies]}
+    if jev_mode is not None:
+        body["jevMode"] = jev_mode
     return Deployment.from_dict(_request_json(ctx, "PUT", path, json_body=body) or {})
 
 
+def set_jev_mode(ctx: ClientContext, machine_id: str, jev_mode: str) -> Tuple[Deployment, bool]:
+    """PUT /api/enforcement/deployments/{id}/jev-mode — change ONLY the Jev mode.
+
+    ``jev_mode`` is ``off|observe|enforce|local`` (``local`` stops FailproofAI
+    Cloud overriding the machine's own mode). Unlike a deploy, this never
+    touches the machine's policy set: a deploy is a full replace of the set, and
+    the set a client can read leaves out disabled policies' assignments, so a
+    mode change sent as a deploy deleted them — and reverted any edit made since
+    the set was read. It still mints a new generation, which is how the machine
+    picks the mode up.
+
+    Returns the deployment and whether anything changed: setting the mode the
+    machine already has changes nothing and mints nothing (``changed: false``).
+    A machine with no deployment is a 404 — a deploy is how it gets its first.
+    """
+    path = f"/api/enforcement/deployments/{machine_id}/jev-mode"
+    data = _request_json(ctx, "PUT", path, json_body={"jevMode": jev_mode}) or {}
+    return Deployment.from_dict(data), bool(data.get("changed", True))
+
+
 def deployment_history(ctx: ClientContext, machine_id: str) -> List[Dict[str, Any]]:
     """GET /api/enforcement/deployments/{id}/history — every generation, newest first."""
     path = f"/api/enforcement/deployments/{machine_id}/history"