failproofai 1.0.9 → 1.0.10

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,72 @@ 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, also when calls run in parallel; a later turn gets it again.
+  Hermes saves a result to a file once it passes 15% of the model's context
+  window (4 characters per token, clamped to 8,000–100,000 characters;
+  `read_file` is never saved) and shows the model a 1,500-character preview.
+  When the full reminder would take the result past 7,500 characters it is
+  compacted: at most three reminders, each policy name cut to 80 characters and
+  each reason to 160, so it always fits inside that preview. It is always
+  attached: on a model whose threshold is the 8,000 floor, a result just under
+  it may be saved because of the reminder, which is then the head of the
+  preview.
+
+  `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 +208,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: