failproofai 1.0.5 → 1.0.6-beta.0

package/dist/worker.mjs

@@ -3483,7 +3483,7 @@ function parsePackPolicyName(canonicalName) {
 }
 
 // package.json
-var version = "1.0.5";
+var version = "1.0.6-beta.0";
 var init_package = () => {};
 
 // src/posthog-key.ts
@@ -10605,7 +10605,20 @@ async function evaluateHookEvent(eventType, cli = "claude", stdinPayload, opts)
         }
       } catch {}
     }
-    return { exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr };
+    return {
+      exitCode: result.exitCode,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      evaluation: {
+        decision: result.decision,
+        policyName: result.policyName,
+        policyNames: result.policyNames ?? (result.policyName ? [result.policyName] : []),
+        reason: result.reason,
+        matchedPolicies,
+        durationMs,
+        toolName: parsed.tool_name ?? null
+      }
+    };
   } finally {
     if (opts?.awaitTelemetryFlush ?? true) {
       await flushHookTelemetry();
@@ -10709,7 +10722,8 @@ function handleConnection(socket, shutdown) {
             type: "hookResult",
             exitCode: result.exitCode,
             stdout: result.stdout,
-            stderr: result.stderr
+            stderr: result.stderr,
+            evaluation: result.evaluation
           }));
         } catch (err) {
           const msg = err instanceof Error ? err.message : String(err);

package/hermes-plugin/README.md

@@ -0,0 +1,133 @@
+# FailproofAI for Hermes
+
+This directory is the native Hermes adapter shipped inside the `failproofai`
+npm package. It keeps policy evaluation in FailproofAI's TypeScript worker and
+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.
+
+## Installation
+
+Run:
+
+```bash
+failproofai policies --install --cli hermes --scope user
+```
+
+FailproofAI copies this directory to every discovered profile at
+`<HERMES_HOME>/plugins/failproofai/` and adds `failproofai` to
+`plugins.enabled` in that profile's `config.yaml`. Reinstall replaces only a
+directory carrying `.failproofai-managed`; an unrelated plugin with the same
+directory name is never overwritten.
+
+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.
+
+## Runtime path
+
+```text
+Hermes pre_tool_call
+  -> native Python plugin
+  -> owner-only failproofaid Unix socket
+  -> warm TypeScript policy worker
+  -> structured allow | deny | instruct verdict
+  -> Hermes-native return value
+```
+
+There is no cloud request and no new CLI process in the tool-call path.
+
+## Decision behavior
+
+- `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.
+
+## Configuration
+
+Settings live under `plugins.entries.failproofai.settings`:
+
+```yaml
+plugins:
+  enabled:
+    - failproofai
+  entries:
+    failproofai:
+      settings:
+        failure_mode: deny
+        connect_timeout_ms: 250
+        evaluation_timeout_ms: 12000
+        instruction_ttl_seconds: 3600
+        max_instruction_rounds: 2
+```
+
+`failure_mode` controls evaluator/protocol failures only. `deny` is the safe
+default. `allow` favors availability when the local daemon cannot return a
+trusted verdict. Ledger failures always allow only the advisory `instruct`
+decision, because otherwise corrupted retry state could block a turn forever.
+
+## Local protocol
+
+Requests and responses use the existing length-prefixed failproofaid Unix
+socket protocol, version 1.
+
+```json
+{
+  "type": "policyEvaluation",
+  "protocolVersion": 1,
+  "integration": "hermes",
+  "event": "pre_tool_call",
+  "payload": {},
+  "cwd": "/workspace/project"
+}
+```
+
+```json
+{
+  "type": "policyResult",
+  "protocolVersion": 1,
+  "decision": "instruct",
+  "policyNames": ["custom/approved-write-route"],
+  "reason": "Use the approved write route.",
+  "matchedPolicies": ["custom/approved-write-route"],
+  "durationMs": 3,
+  "toolName": "Write"
+}
+```
+
+Requests are limited to 1 MiB and responses to 16 MiB. Invalid JSON, unknown
+message types, version mismatch, timeout, and socket failure are treated as
+untrusted evaluation failures.
+
+## Diagnostics and rollback
+
+`failproofai config --status` reports each existing Hermes profile as healthy,
+disabled, incomplete, or duplicated with a legacy shell hook. Hermes-side load
+errors are available through:
+
+```bash
+HERMES_PLUGINS_DEBUG=1 hermes plugins list
+hermes plugins doctor ~/.hermes/plugins/failproofai --ci
+hermes logs --level WARNING
+```
+
+Use a temporary `HERMES_HOME` for development and compatibility tests. Remove
+the integration with:
+
+```bash
+failproofai policies --uninstall --cli hermes --scope user
+```
+
+Uninstall removes the config registration and only the plugin directory marked
+as FailproofAI-managed.

package/hermes-plugin/__init__.py

@@ -0,0 +1,248 @@
+"""Native Hermes bridge for FailproofAI policy enforcement."""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Any, Mapping
+
+from .client import PolicyVerdict, evaluate_policy
+from .ledger import InstructionLedger, LedgerError
+
+logger = logging.getLogger(__name__)
+
+_PROTOCOL_CONTEXT = (
+    "When a tool result starts with FAILPROOF INSTRUCTION, treat it as policy guidance. "
+    "Reconsider the attempted action before retrying. Do not evade or ignore the instruction; "
+    "change tools, arguments, targets, or side effects only when the instruction requires it. "
+    "If you cannot follow the instruction, stop and explain why."
+)
+
+
+def _bounded_int(value: object, default: int, minimum: int, maximum: int) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return default
+    return min(max(parsed, minimum), maximum)
+
+
+def _profile_name() -> str:
+    explicit = os.environ.get("HERMES_PROFILE", "").strip()
+    if explicit:
+        return explicit
+    configured_home = os.environ.get("HERMES_HOME", "").strip()
+    home = Path(configured_home).expanduser() if configured_home else Path.home() / ".hermes"
+    if home.parent.name == "profiles":
+        return home.name
+    return "default"
+
+
+def _string(value: object) -> str:
+    return value if isinstance(value, str) else ""
+
+
+class FailproofAIPlugin:
+    def __init__(self, ctx: Any) -> None:
+        self.ctx = ctx
+        self.profile = _profile_name()
+        self.failure_mode = str(ctx.get_config("failure_mode", "deny")).strip().lower()
+        self.connect_timeout_ms = _bounded_int(
+            ctx.get_config("connect_timeout_ms", 250), 250, 25, 5_000
+        )
+        self.evaluation_timeout_ms = _bounded_int(
+            ctx.get_config("evaluation_timeout_ms", 12_000), 12_000, 100, 29_000
+        )
+        ttl_seconds = _bounded_int(
+            ctx.get_config("instruction_ttl_seconds", 3_600), 3_600, 60, 86_400
+        )
+        max_rounds = _bounded_int(
+            ctx.get_config("max_instruction_rounds", 2), 2, 0, 10
+        )
+        self.ledger = InstructionLedger(
+            Path(ctx.state.data_dir) / "instructions.db",
+            ttl_seconds=ttl_seconds,
+            max_rounds=max_rounds,
+        )
+
+    def _fallback(self, error: Exception) -> dict[str, str] | None:
+        logger.error("FailproofAI evaluator unavailable: %s", error)
+        if self.failure_mode == "allow":
+            return None
+        return {
+            "action": "block",
+            "message": (
+                "FailproofAI could not verify this tool call because the local policy "
+                "evaluator is unavailable. Check `failproofai status` before retrying."
+            ),
+        }
+
+    def _evaluate(self, event: str, payload: Mapping[str, Any]) -> PolicyVerdict:
+        cwd = _string(payload.get("cwd")) or os.getcwd()
+        return evaluate_policy(
+            event=event,
+            payload=payload,
+            cwd=cwd,
+            connect_timeout_ms=self.connect_timeout_ms,
+            evaluation_timeout_ms=self.evaluation_timeout_ms,
+        )
+
+    def pre_tool_call(
+        self,
+        tool_name: str = "",
+        args: Mapping[str, Any] | None = None,
+        session_id: str = "",
+        task_id: str = "",
+        tool_call_id: str = "",
+        turn_id: str = "",
+        api_request_id: str = "",
+        **kwargs: Any,
+    ) -> dict[str, str] | None:
+        payload = {
+            "hook_event_name": "pre_tool_call",
+            "tool_name": tool_name,
+            "tool_input": dict(args or {}),
+            "session_id": session_id,
+            "cwd": _string(kwargs.get("cwd")) or os.getcwd(),
+            "hermes": {
+                "profile": self.profile,
+                "task_id": task_id,
+                "tool_call_id": tool_call_id,
+                "turn_id": turn_id,
+                "api_request_id": api_request_id,
+            },
+        }
+        try:
+            verdict = self._evaluate("pre_tool_call", payload)
+        except Exception as exc:
+            return self._fallback(exc)
+
+        if verdict.decision == "allow":
+            return None
+        if verdict.decision == "deny":
+            return {
+                "action": "block",
+                "message": verdict.reason or "Blocked by FailproofAI policy.",
+            }
+
+        reason = verdict.reason or "Reconsider this tool call before retrying."
+        try:
+            action = self.ledger.decide(
+                profile=self.profile,
+                session_id=session_id,
+                task_id=task_id,
+                turn_id=turn_id,
+                api_request_id=api_request_id,
+                policy_names=verdict.policy_names,
+                reason=reason,
+                scope_key=verdict.tool_name or tool_name or "unknown-tool",
+            )
+        except LedgerError as exc:
+            # An advisory instruction must never become an indefinite denial
+            # because its local retry state is unavailable.
+            logger.error("FailproofAI instruction state unavailable; allowing: %s", exc)
+            return None
+
+        if not action.block:
+            if action.status in {"missing-correlation-id", "turn-cap"}:
+                logger.warning("FailproofAI instruction allowed in degraded state: %s", action.status)
+            return None
+
+        policies = ", ".join(verdict.policy_names) or "unknown policy"
+        return {
+            "action": "block",
+            "message": (
+                f"FAILPROOF INSTRUCTION ({policies})\n\n{reason}\n\n"
+                "Reconsider the attempted action, then make a corrected tool call. "
+                "Do not route around this instruction with an equivalent ungoverned action."
+            ),
+        }
+
+    def _observe(self, event: str, payload: Mapping[str, Any]) -> None:
+        try:
+            self._evaluate(event, payload)
+        except Exception as exc:
+            logger.warning("FailproofAI observation failed for %s: %s", event, exc)
+
+    def post_tool_call(
+        self,
+        tool_name: str = "",
+        args: Mapping[str, Any] | None = None,
+        result: Any = None,
+        session_id: str = "",
+        **kwargs: Any,
+    ) -> None:
+        self._observe(
+            "post_tool_call",
+            {
+                "hook_event_name": "post_tool_call",
+                "tool_name": tool_name,
+                "tool_input": dict(args or {}),
+                "tool_response": result,
+                "session_id": session_id,
+                "cwd": _string(kwargs.get("cwd")) or os.getcwd(),
+                "hermes": {"profile": self.profile, **kwargs},
+            },
+        )
+
+    def on_session_start(self, session_id: str = "", **kwargs: Any) -> None:
+        self._observe(
+            "on_session_start",
+            {
+                "hook_event_name": "on_session_start",
+                "session_id": session_id,
+                "cwd": _string(kwargs.get("cwd")) or os.getcwd(),
+                "hermes": {"profile": self.profile, **kwargs},
+            },
+        )
+
+    def on_session_end(self, session_id: str = "", **kwargs: Any) -> None:
+        self._observe(
+            "on_session_end",
+            {
+                "hook_event_name": "on_session_end",
+                "session_id": session_id,
+                "cwd": _string(kwargs.get("cwd")) or os.getcwd(),
+                "hermes": {"profile": self.profile, **kwargs},
+            },
+        )
+        self._clear_session(session_id)
+
+    def subagent_stop(self, session_id: str = "", **kwargs: Any) -> None:
+        self._observe(
+            "subagent_stop",
+            {
+                "hook_event_name": "subagent_stop",
+                "session_id": session_id,
+                "cwd": _string(kwargs.get("cwd")) or os.getcwd(),
+                "hermes": {"profile": self.profile, **kwargs},
+            },
+        )
+
+    def pre_llm_call(self, **kwargs: Any) -> dict[str, str]:
+        return {"context": _PROTOCOL_CONTEXT}
+
+    def on_session_reset(self, session_id: str = "", **kwargs: Any) -> None:
+        self._clear_session(session_id)
+
+    def on_session_finalize(self, session_id: str = "", **kwargs: Any) -> None:
+        self._clear_session(session_id)
+
+    def _clear_session(self, session_id: str) -> None:
+        try:
+            self.ledger.clear_session(session_id)
+        except LedgerError as exc:
+            logger.warning("FailproofAI instruction cleanup failed: %s", exc)
+
+
+def register(ctx: Any) -> None:
+    plugin = FailproofAIPlugin(ctx)
+    ctx.register_hook("pre_tool_call", plugin.pre_tool_call)
+    ctx.register_hook("post_tool_call", plugin.post_tool_call)
+    ctx.register_hook("pre_llm_call", plugin.pre_llm_call)
+    ctx.register_hook("on_session_start", plugin.on_session_start)
+    ctx.register_hook("on_session_end", plugin.on_session_end)
+    ctx.register_hook("on_session_reset", plugin.on_session_reset)
+    ctx.register_hook("on_session_finalize", plugin.on_session_finalize)
+    ctx.register_hook("subagent_stop", plugin.subagent_stop)

package/hermes-plugin/client.py

@@ -0,0 +1,134 @@
+"""Versioned Unix-socket client for failproofaid policy evaluation."""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import struct
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+PROTOCOL_VERSION = 1
+MAX_FRAME_BYTES = 16 * 1024 * 1024
+MAX_REQUEST_BYTES = 1024 * 1024
+
+
+class EvaluationError(RuntimeError):
+    """The daemon could not return a trustworthy policy verdict."""
+
+
+@dataclass(frozen=True)
+class PolicyVerdict:
+    decision: str
+    policy_names: tuple[str, ...]
+    reason: str | None
+    matched_policies: tuple[str, ...]
+    duration_ms: int
+    tool_name: str | None
+
+
+def daemon_socket_path() -> Path:
+    override = os.environ.get("FAILPROOFAI_DAEMON_SOCKET", "").strip()
+    if override:
+        return Path(override).expanduser()
+    root = os.environ.get("FAILPROOFAI_HOME", "").strip()
+    home = Path(root).expanduser() if root else Path.home() / ".failproofai"
+    return home / "run" / "failproofaid.sock"
+
+
+def _read_exact(sock: socket.socket, length: int) -> bytes:
+    chunks: list[bytes] = []
+    remaining = length
+    while remaining:
+        chunk = sock.recv(remaining)
+        if not chunk:
+            raise EvaluationError("failproofaid closed the connection before returning a verdict")
+        chunks.append(chunk)
+        remaining -= len(chunk)
+    return b"".join(chunks)
+
+
+def _string_list(value: object, field: str) -> tuple[str, ...]:
+    if not isinstance(value, Sequence) or isinstance(value, (str, bytes, bytearray)):
+        raise EvaluationError(f"failproofaid returned an invalid {field}")
+    if not all(isinstance(item, str) for item in value):
+        raise EvaluationError(f"failproofaid returned an invalid {field}")
+    return tuple(value)
+
+
+def evaluate_policy(
+    *,
+    event: str,
+    payload: Mapping[str, Any],
+    cwd: str | None,
+    connect_timeout_ms: int = 250,
+    evaluation_timeout_ms: int = 12_000,
+) -> PolicyVerdict:
+    request = {
+        "type": "policyEvaluation",
+        "protocolVersion": PROTOCOL_VERSION,
+        "integration": "hermes",
+        "event": event,
+        "payload": dict(payload),
+        "cwd": cwd,
+    }
+    try:
+        body = json.dumps(
+            request,
+            ensure_ascii=False,
+            separators=(",", ":"),
+            default=lambda value: repr(value),
+        ).encode("utf-8")
+    except (TypeError, ValueError) as exc:
+        raise EvaluationError(f"could not encode policy request: {exc}") from exc
+    if len(body) > MAX_REQUEST_BYTES:
+        raise EvaluationError("policy request exceeds the 1 MiB limit")
+
+    try:
+        with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock:
+            sock.settimeout(max(connect_timeout_ms, 1) / 1000)
+            sock.connect(str(daemon_socket_path()))
+            sock.settimeout(max(evaluation_timeout_ms, 1) / 1000)
+            sock.sendall(struct.pack(">I", len(body)) + body)
+            declared_length = struct.unpack(">I", _read_exact(sock, 4))[0]
+            if declared_length > MAX_FRAME_BYTES:
+                raise EvaluationError("failproofaid response exceeds the 16 MiB limit")
+            response = json.loads(_read_exact(sock, declared_length).decode("utf-8"))
+    except EvaluationError:
+        raise
+    except (OSError, UnicodeError, ValueError, struct.error) as exc:
+        raise EvaluationError(f"failproofaid evaluation failed: {exc}") from exc
+
+    if not isinstance(response, dict):
+        raise EvaluationError("failproofaid returned a non-object response")
+    if response.get("protocolVersion") != PROTOCOL_VERSION:
+        raise EvaluationError("failproofaid protocol version mismatch")
+    if response.get("type") == "error":
+        message = response.get("message")
+        raise EvaluationError(str(message or "failproofaid could not evaluate the policy"))
+    if response.get("type") != "policyResult":
+        raise EvaluationError("failproofaid does not support native policy evaluation")
+
+    decision = response.get("decision")
+    if decision not in {"allow", "deny", "instruct"}:
+        raise EvaluationError("failproofaid returned an invalid policy decision")
+    reason = response.get("reason")
+    if reason is not None and not isinstance(reason, str):
+        raise EvaluationError("failproofaid returned an invalid policy reason")
+    duration_ms = response.get("durationMs", 0)
+    if not isinstance(duration_ms, int) or duration_ms < 0:
+        raise EvaluationError("failproofaid returned an invalid evaluation duration")
+    tool_name = response.get("toolName")
+    if tool_name is not None and not isinstance(tool_name, str):
+        raise EvaluationError("failproofaid returned an invalid tool name")
+
+    return PolicyVerdict(
+        decision=decision,
+        policy_names=_string_list(response.get("policyNames", []), "policyNames"),
+        reason=reason,
+        matched_policies=_string_list(response.get("matchedPolicies", []), "matchedPolicies"),
+        duration_ms=duration_ms,
+        tool_name=tool_name,
+    )