failproofai 1.0.9-beta.2 → 1.0.10-beta.1

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

@@ -19,6 +19,7 @@ Two auth modes, and they never mix:
 from __future__ import annotations
 
 import json as _json
+import re
 import uuid
 from dataclasses import dataclass
 from enum import Enum
@@ -264,8 +265,43 @@ def _path(ctx: ClientContext, path: str) -> str:
     return path
 
 
+# A request id as the server may echo it: our own 32 hex, or a dashed UUID from
+# an older server. Anything else is not put on an error a person will paste.
+_SANE_REQUEST_ID = re.compile(r"^[A-Za-z0-9-]{1,64}$")
+
+
+def _new_request_id() -> str:
+    """One id per HTTP request — a W3C trace id, the shape the server keeps as-is."""
+    return uuid.uuid4().hex
+
+
+def _request_id_of(response: httpx.Response) -> Optional[str]:
+    """The failed request's id: the server's echo, else the one this CLI sent.
+
+    The server echoes ours back, so the two normally agree. The fallback matters
+    when something in front of the API answered instead — a proxy, a front door —
+    and a ref is still worth printing: our id is in the dashboard's access logs.
+    """
+    echoed = (response.headers.get("x-request-id") or "").strip()
+    if _SANE_REQUEST_ID.match(echoed):
+        return echoed
+    try:
+        return response.request.headers.get("x-request-id")
+    except RuntimeError:  # a Response built without a request (tests)
+        return None
+
+
+def _sent_request_id(exc: httpx.RequestError) -> Optional[str]:
+    """The id of a request that never got an answer."""
+    try:
+        return exc.request.headers.get("x-request-id")
+    except RuntimeError:
+        return None
+
+
 def _client(ctx: ClientContext, *, timeout: Any = None) -> httpx.Client:
-    headers = {"x-request-id": uuid.uuid4().hex}
+    # One id per client, and every call site opens a fresh client per request.
+    headers = {"x-request-id": _new_request_id()}
     cookies = None
     # Bearer XOR cookie — an `else`, never two independent `if`s. Sending both
     # would hand a human's `ae_session` to `/v1` alongside the key, and every
@@ -355,7 +391,7 @@ def _raise_for_status(response: httpx.Response, ctx: ClientContext) -> None:
                     "the dashboard's login page, so it landed on the web app instead of "
                     "the API.",
                     status=response.status_code,
-                    request_id=response.headers.get("x-request-id"),
+                    request_id=_request_id_of(response),
                     hint="point --base-url at the server itself, e.g. http://localhost:8080",
                 )
         # Session mode is deliberately left alone for the /login case: that 3xx is
@@ -375,22 +411,23 @@ def _raise_for_status(response: httpx.Response, ctx: ClientContext) -> None:
                 "The request was redirected and did not reach the API, so it had no "
                 "effect. Nothing was changed.",
                 status=response.status_code,
-                request_id=response.headers.get("x-request-id"),
+                request_id=_request_id_of(response),
                 hint=(
                     "check --base-url: a redirect here usually means http:// where the "
                     "server wants https://, or a front door in front of the API"
                 ),
             )
         return
-    request_id = response.headers.get("x-request-id")
+    request_id = _request_id_of(response)
     message = _extract_error(response)
     if response.status_code == 401:
         if key_mode:
             raise AuthError(
                 "The API key was rejected. It may be revoked, mistyped, or issued by a "
-                "different deployment than --base-url points at."
+                "different deployment than --base-url points at.",
+                request_id=request_id,
             )
-        raise AuthError("Session expired or not logged in. Run fp login.")
+        raise AuthError("Session expired or not logged in. Run fp login.", request_id=request_id)
     if response.status_code == 403:
         needed = _required_permission(response)
         if key_mode:
@@ -406,10 +443,13 @@ def _raise_for_status(response: httpx.Response, ctx: ClientContext) -> None:
             raise ForbiddenError(
                 f"{what}, or it cannot act for this org — the server answers 403 for both.",
                 hint="check the key's grants, and the org you targeted with --org / FP_ORG",
+                request_id=request_id,
             )
         if needed:
-            raise ForbiddenError(f"you don't have the {needed} permission")
-        raise ForbiddenError(message or "you don't have permission for this action")
+            raise ForbiddenError(f"you don't have the {needed} permission", request_id=request_id)
+        raise ForbiddenError(
+            message or "you don't have permission for this action", request_id=request_id
+        )
     if response.status_code == 404:
         # In key mode a 404 has TWO very different causes, and the wrong reading
         # sends people hunting for a server bug that isn't there:
@@ -434,7 +474,7 @@ def _raise_for_status(response: httpx.Response, ctx: ClientContext) -> None:
                     request_id=request_id,
                     hint="point --base-url at the server itself, e.g. http://localhost:8080",
                 )
-        raise NotFoundError(message or "Not found.")
+        raise NotFoundError(message or "Not found.", request_id=request_id)
     if response.status_code == 429:
         retry_after = response.headers.get("retry-after")
         wait = f" Retry after {retry_after}s." if retry_after else " Please wait a moment and try again."
@@ -458,7 +498,8 @@ def _get_json(ctx: ClientContext, path: str, params: Optional[Dict[str, Any]] =
             response = client.get(url, params=clean)
     except httpx.RequestError as exc:
         raise NetworkError(
-            f"Cannot reach FailproofAI Cloud at {ctx.base_url}: {exc}"
+            f"Cannot reach FailproofAI Cloud at {ctx.base_url}: {exc}",
+            request_id=_sent_request_id(exc),
         )
     _raise_for_status(response, ctx)
     # A 2xx with an empty or non-JSON body is anomalous for a read (e.g. a proxy or
@@ -470,7 +511,7 @@ def _get_json(ctx: ClientContext, path: str, params: Optional[Dict[str, Any]] =
         raise ApiError(
             "The dashboard returned a malformed (non-JSON) response.",
             status=response.status_code,
-            request_id=response.headers.get("x-request-id"),
+            request_id=_request_id_of(response),
         )
 
 
@@ -495,7 +536,8 @@ def _request_json(
             response = client.request(method, url, json=json_body, params=clean)
     except httpx.RequestError as exc:
         raise NetworkError(
-            f"Cannot reach FailproofAI Cloud at {ctx.base_url}: {exc}"
+            f"Cannot reach FailproofAI Cloud at {ctx.base_url}: {exc}",
+            request_id=_sent_request_id(exc),
         )
     _raise_for_status(response, ctx)
     # A genuinely empty body (204, or a 200 with no content) is a legitimate
@@ -514,7 +556,7 @@ def _request_json(
             "The dashboard returned a malformed (non-JSON) response, so the request "
             "may not have been applied.",
             status=response.status_code,
-            request_id=response.headers.get("x-request-id"),
+            request_id=_request_id_of(response),
         )
 
 
@@ -575,7 +617,8 @@ def org_is_accessible(ctx: ClientContext, slug: str) -> bool:
             response = client.get(_path(probe, "/api/access-granters"))
     except httpx.RequestError as exc:
         raise NetworkError(
-            f"Cannot reach FailproofAI Cloud at {ctx.base_url}: {exc}"
+            f"Cannot reach FailproofAI Cloud at {ctx.base_url}: {exc}",
+            request_id=_sent_request_id(exc),
         )
     if response.status_code == 200:
         return True

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

@@ -26,9 +26,24 @@ class FpCliError(click.ClickException):
 
     exit_code = 1
 
-    def __init__(self, message: str, *, hint: Optional[str] = None) -> None:
+    def __init__(
+        self,
+        message: str,
+        *,
+        hint: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
         super().__init__(message)
         self.hint = hint
+        # The id of the HTTP request that failed — the server's echo, else the
+        # one this CLI sent. On every typed error, not only ApiError, so a 403 or
+        # a 404 is as traceable in the server's logs as a 500.
+        self.request_id = request_id
+
+    @property
+    def ref(self) -> Optional[str]:
+        """What a person reads and pastes: the first 8 chars of the request id."""
+        return self.request_id[:8] if self.request_id else None
 
 
 class KeyModeUnsupportedError(FpCliError):
@@ -85,9 +100,8 @@ class ApiError(FpCliError):
         request_id: Optional[str] = None,
         hint: Optional[str] = None,
     ) -> None:
-        super().__init__(message, hint=hint)
+        super().__init__(message, hint=hint, request_id=request_id)
         self.status = status
-        self.request_id = request_id
 
     def format_message(self) -> str:
         parts = [self.message]

package/.next/standalone/fp-cloud-cli/tests/test_request_id.py

@@ -0,0 +1,111 @@
+"""Every CLI request carries its own id, and every failure names it.
+
+A customer pastes `ref 4bf92f35`; support finds every server log line of that
+request with one query. That only works if (a) each HTTP request has a distinct
+id, (b) every typed error — not just ApiError — carries it, and (c) the id is
+still there when something in front of the API answered without echoing one.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+import httpx
+import pytest
+import respx
+
+from fp_cli import client as api
+from fp_cli.app import app
+from fp_cli.client import ClientContext
+from fp_cli.errors import ApiError, AuthError, ForbiddenError, NetworkError, NotFoundError
+
+BASE = "http://dash.test"
+TRACE_ID = re.compile(r"^[0-9a-f]{32}$")
+SERVER_ID = "4bf92f3577b34da6a3ce929d0e0e4736"
+
+
+def ctx() -> ClientContext:
+    return ClientContext(base_url=BASE, token="tok")
+
+
+@respx.mock
+def test_each_request_gets_its_own_trace_id():
+    route = respx.get(f"{BASE}/api/sessions").mock(
+        return_value=httpx.Response(200, json={"sessions": [], "next_cursor": None})
+    )
+    api.list_sessions(ctx())
+    api.list_sessions(ctx())
+    ids = [call.request.headers["x-request-id"] for call in route.calls]
+    assert len(ids) == 2
+    assert all(TRACE_ID.match(i) for i in ids), ids
+    assert ids[0] != ids[1]
+
+
+@pytest.mark.parametrize(
+    ("status", "error_type"),
+    [(401, AuthError), (403, ForbiddenError), (404, NotFoundError), (500, ApiError)],
+)
+@respx.mock
+def test_every_typed_error_carries_the_servers_request_id(status, error_type):
+    respx.get(f"{BASE}/api/sessions").mock(
+        return_value=httpx.Response(status, json={"error": "x"}, headers={"x-request-id": SERVER_ID})
+    )
+    with pytest.raises(error_type) as excinfo:
+        api.list_sessions(ctx())
+    assert excinfo.value.request_id == SERVER_ID
+    assert excinfo.value.ref == SERVER_ID[:8]
+
+
+@respx.mock
+def test_without_an_echo_the_error_names_the_id_we_sent():
+    # A proxy or front door answered: no x-request-id on the response. The id we
+    # sent is still the one in the dashboard's access logs.
+    route = respx.get(f"{BASE}/api/sessions").mock(return_value=httpx.Response(502, text="bad gateway"))
+    with pytest.raises(ApiError) as excinfo:
+        api.list_sessions(ctx())
+    sent = route.calls.last.request.headers["x-request-id"]
+    assert excinfo.value.request_id == sent
+
+
+@respx.mock
+def test_an_unsane_echo_is_not_put_on_the_error():
+    route = respx.get(f"{BASE}/api/sessions").mock(
+        return_value=httpx.Response(500, json={"error": "x"}, headers={"x-request-id": "a b c"})
+    )
+    with pytest.raises(ApiError) as excinfo:
+        api.list_sessions(ctx())
+    assert excinfo.value.request_id == route.calls.last.request.headers["x-request-id"]
+
+
+@respx.mock
+def test_a_network_error_names_the_id_it_sent():
+    route = respx.get(f"{BASE}/api/sessions").mock(side_effect=httpx.ConnectError("refused"))
+    with pytest.raises(NetworkError) as excinfo:
+        api.list_sessions(ctx())
+    assert excinfo.value.request_id == route.calls.last.request.headers["x-request-id"]
+    # Exit code contract unchanged.
+    assert excinfo.value.exit_code == 3
+
+
+@respx.mock
+def test_the_human_error_line_shows_the_ref(logged_in, runner):
+    respx.get(f"{BASE}/api/sessions").mock(
+        return_value=httpx.Response(403, json={"error": "forbidden"}, headers={"x-request-id": SERVER_ID})
+    )
+    result = runner.invoke(app, ["sessions"])
+    assert result.exit_code == 5
+    assert f"ref {SERVER_ID[:8]}" in result.stderr
+
+
+@respx.mock
+def test_the_json_envelope_carries_the_full_id_for_non_api_errors(logged_in, runner):
+    respx.get(f"{BASE}/api/sessions").mock(
+        return_value=httpx.Response(403, json={"error": "forbidden"}, headers={"x-request-id": SERVER_ID})
+    )
+    result = runner.invoke(app, ["--json", "sessions"])
+    assert result.exit_code == 5
+    data = json.loads(result.stdout)
+    assert data["request_id"] == SERVER_ID
+    # The ref is for humans; the envelope's message stays clean.
+    assert "ref " not in data["error"]

package/.next/standalone/fp-cloud-cli/uv.lock

@@ -541,9 +541,9 @@ wheels = [
 
 [[package]]
 name = "urllib3"
-version = "2.7.0"
+version = "2.8.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/53/0c/06f8b233b8fd13b9e5ee11424ef85419ba0d8ba0b3138bf360be2ff56953/urllib3-2.7.0.tar.gz", hash = "sha256:231e0ec3b63ceb14667c67be60f2f2c40a518cb38b03af60abc813da26505f4c", size = 433602, upload-time = "2026-05-07T16:13:18.596Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/e3/05/b17359e1cefb4f909b5e40b1b90a496d987258916dbbf88e842c729f510e/urllib3-2.8.0.tar.gz", hash = "sha256:63bf2ead4c879426ebf22ef2a781eeb4aa3b4ae798a0435506f8687fd5bb9b63", size = 458972, upload-time = "2026-09-15T19:29:36.253Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/7f/3e/5db95bcf282c52709639744ca2a8b149baccf648e39c8cc87553df9eae0c/urllib3-2.7.0-py3-none-any.whl", hash = "sha256:9fb4c81ebbb1ce9531cce37674bbc6f1360472bc18ca9a553ede278ef7276897", size = 131087, upload-time = "2026-05-07T16:13:17.151Z" },
+    { url = "https://files.pythonhosted.org/packages/92/9d/c4e665119135114480843e7ab388fa94d8480650450e6f8e26b70d323a4c/urllib3-2.8.0-py3-none-any.whl", hash = "sha256:0cf3cae568d36aa9576b28dfb35f11328f1cb974ca7647d9475ebb86c75ac6e3", size = 135717, upload-time = "2026-09-15T19:29:34.577Z" },
 ]

package/.next/standalone/hermes-plugin/README.md

@@ -7,6 +7,11 @@ translates structured verdicts into Hermes-native hook behavior.
 Validated contract: Hermes 0.21.3 at
 `4d55ca91656ac5f83e1506679b7f81e0238e5e16`. The plugin uses only documented
 manifest v2 fields, `PluginContext` methods/state, and keyword hook payloads.
+Hermes 0.20.0 is also supported: its `PluginContext` has no `get_config` or
+`state` (both arrived in 0.20.1), so the plugin reads the same
+`plugins.entries.failproofai` settings through Hermes' config loader and keeps
+its ledger in the directory `state.data_dir` would name, which a later Hermes
+upgrade reuses.
 
 ## Installation
 
@@ -40,6 +45,14 @@ Legacy FailproofAI shell hooks are removed during migration. Operator-owned
 hooks and unrelated plugin settings are preserved. No dashboard deployment or
 backtest is part of installation.
 
+## Supported Hermes versions
+
+Hermes 0.20.0 and later. Tested on 0.20.0 (v2026.8.3), 0.20.1 (v2026.8.13),
+0.20.6 (v2026.8.27), 0.21.0 (v2026.8.31), 0.21.3 (v2026.9.14), 0.21.5
+(v2026.9.24, the latest release) and upstream main (2026-10-05).
+Hermes 0.20.0 has no `ctx.get_config` or `ctx.state`; the plugin detects that and
+reads the same settings and state directory another way.
+
 ## Runtime path
 
 ```text
@@ -49,6 +62,8 @@ Hermes pre_tool_call
   -> warm TypeScript policy worker
   -> structured allow | deny | instruct verdict
   -> Hermes-native return value
+Hermes tool_execution middleware (wraps the real call)
+  -> instruct reminder placed at the start of the call's own result
 ```
 
 There is no cloud request and no new CLI process in the tool-call path.
@@ -57,16 +72,67 @@ There is no cloud request and no new CLI process in the tool-call path.
 
 - `allow`: return no directive; Hermes runs the tool.
 - `deny`: always return `{"action":"block","message":"..."}`.
-- `instruct`: persist delivery state, block the first attempt with a
-  model-visible `FAILPROOF INSTRUCTION`, keep the same API request blocked, then
-  allow a later API iteration for the same instruction scope.
-
-The default instruction scope is profile + session + task + turn + policy
-fingerprint + canonical tool. The persistent SQLite ledger lives below Hermes'
-profile-scoped plugin data directory. Two distinct instruction interruptions
-are allowed per turn by default; after that, advisory instructions fail open so
-they cannot create an infinite retry loop. A real deny is never bypassed by the
-ledger.
+- `instruct`: the call runs, and the reminder is placed at the **start** of its
+  result, so it survives the 1,500-character preview Hermes keeps of a large
+  result:
+  - a JSON object result gets `"failproof_policy_reminder"` as its first key
+    (the rest is unchanged, so `json.loads` consumers such as `execute_code`
+    scripts keep working). A field of that name the tool returned itself is
+    moved to `"tool_failproof_policy_reminder"`, never merged into the
+    reminder;
+  - other text gets a leading `[FailproofAI policy reminder (<policies>)] ...`
+    line (an `Error...` result keeps that prefix and gets the line at its end);
+  - a list of content blocks or a multimodal envelope gets a leading text block,
+    leaving image blocks intact.
+
+  Tool calls made by an `execute_code` script hand their reminder to the outer
+  `execute_code` result, which is the one the model reads, and the script gets
+  its own result untouched, so nothing it prints, writes or sends carries the
+  reminder. (With no open outer call to carry it, the inner result keeps it.)
+  A result Hermes reports as blocked (`{"error": ...}` only) is never
+  annotated. This uses Hermes' `tool_execution` middleware
+  (`ctx.register_middleware`, present unchanged in 0.20.0, 0.21.x and main).
+
+  A policy's reminder (same policy and reason) is attached once per Hermes
+  session + turn; a later turn gets it again. When the full reminder would take
+  the result past 7,500 characters it is shortened to the policy names and the
+  first 160 characters of the reason, so it never pushes a result over Hermes'
+  8,000-character persistence threshold and never fills the 1,500-character
+  preview of a result already past it.
+
+  `instruct` therefore no longer stops the action first on Hermes: use `deny`
+  when an action must not happen at all.
+
+Where Hermes offers no `tool_execution` middleware, `instruct` falls back to
+holding the call once: persist delivery state, return model-visible
+`FailproofAI policy guidance (...)` ("apply it, then continue; repeating the
+same call is allowed"), keep the same API request held, then allow a later API
+iteration. That fallback's scope is profile + session + task + turn + policy
+fingerprint — not the tool, so moving the same work to another tool (for
+example `execute_code`) is not held again.
+The persistent SQLite ledger lives below Hermes' profile-scoped plugin data
+directory. Two distinct instruction interruptions are allowed per turn by
+default; after that, advisory instructions fail open so they cannot create an
+infinite retry loop. A real deny is never bypassed by the ledger.
+
+Every model turn also receives a short protocol note (`pre_llm_call`): a
+`failproof_policy_reminder` is an operator rule added by FailproofAI (not tool
+data) about a call that ran normally and is never to be quoted, repeated or
+mentioned in replies, messages or files, a FailproofAI block means that action
+must not run by any route, and `FailproofAI policy guidance` held a call only once.
+
+No hook raises: `pre_tool_call` blocks on any internal error (Hermes 0.20.0 and
+0.21.x would treat a raised exception as allow), observer hooks log and return,
+and the middleware falls back to the plain result. One evaluation, connect
+included, is capped at 25 seconds (`evaluation_timeout_ms`, default 12000):
+Hermes 0.21.x abandons a `pre_tool_call` after 30 seconds and then blocks every
+call for 60. Observer hooks wait at most 2 seconds, so against a hung daemon a
+blocked call costs the evaluation deadline plus 2 seconds, not twice the
+deadline.
+
+Tool names are canonicalized in the daemon: Hermes 0.21's `process_manage`,
+`cronjob_manage` and `todo_list` match policies written for 0.20's `process`,
+`cronjob` and `todo`.
 
 ## Configuration
 
@@ -137,6 +203,13 @@ hermes plugins doctor ~/.hermes/plugins/failproofai --ci
 hermes logs --level WARNING
 ```
 
+Each `register()` writes `heartbeat.json` beside `instructions.db` in the
+profile's plugin data directory (`plugin-data/agent-plugin-failproofai-5296f299/`):
+pid, Hermes version, `HERMES_HOME`, profile, the plugin's real path and version,
+the hooks and middleware Hermes accepted, `register_ok` and a timestamp. It is
+the proof of what a running Hermes process actually loaded, which
+`hermes plugins list` (config only) cannot show; Hermes' log gets one INFO line.
+
 Use a temporary `HERMES_HOME` for development and compatibility tests. Remove
 the integration with: