failproofai 1.0.5 → 1.0.6-beta.0

package/hermes-plugin/ledger.py

@@ -0,0 +1,187 @@
+"""Persistent, bounded delivery state for FailproofAI instruct decisions."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Sequence
+
+
+class LedgerError(RuntimeError):
+    """Instruction state could not be read or updated safely."""
+
+
+@dataclass(frozen=True)
+class InstructionAction:
+    block: bool
+    status: str
+
+
+class InstructionLedger:
+    def __init__(self, path: Path, *, ttl_seconds: int = 3600, max_rounds: int = 2) -> None:
+        self.path = path
+        self.ttl_seconds = max(60, int(ttl_seconds))
+        self.max_rounds = max(0, int(max_rounds))
+        self._init_lock = threading.Lock()
+        self._initialized = False
+
+    def _connect(self) -> sqlite3.Connection:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        connection = sqlite3.connect(self.path, timeout=0.25, isolation_level=None)
+        connection.execute("PRAGMA busy_timeout = 250")
+        connection.execute("PRAGMA journal_mode = WAL")
+        connection.execute("PRAGMA synchronous = NORMAL")
+        return connection
+
+    def _ensure_schema(self) -> None:
+        if self._initialized:
+            return
+        with self._init_lock:
+            if self._initialized:
+                return
+            try:
+                with self._connect() as connection:
+                    connection.execute(
+                        """
+                        CREATE TABLE IF NOT EXISTS instruction_deliveries (
+                          delivery_key TEXT PRIMARY KEY,
+                          profile TEXT NOT NULL,
+                          session_id TEXT NOT NULL,
+                          task_id TEXT NOT NULL,
+                          turn_id TEXT NOT NULL,
+                          policy_fingerprint TEXT NOT NULL,
+                          scope_key TEXT NOT NULL,
+                          blocked_api_request_id TEXT NOT NULL,
+                          acknowledged_api_request_id TEXT,
+                          state TEXT NOT NULL,
+                          created_at_ms INTEGER NOT NULL,
+                          expires_at_ms INTEGER NOT NULL
+                        )
+                        """
+                    )
+                    connection.execute(
+                        """
+                        CREATE INDEX IF NOT EXISTS instruction_deliveries_turn
+                        ON instruction_deliveries(profile, session_id, task_id, turn_id, expires_at_ms)
+                        """
+                    )
+            except sqlite3.Error as exc:
+                raise LedgerError(f"could not initialize instruction state: {exc}") from exc
+            self._initialized = True
+
+    @staticmethod
+    def _digest(parts: Sequence[str]) -> str:
+        encoded = json.dumps(list(parts), ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+        return hashlib.sha256(encoded).hexdigest()
+
+    def decide(
+        self,
+        *,
+        profile: str,
+        session_id: str,
+        task_id: str,
+        turn_id: str,
+        api_request_id: str,
+        policy_names: Sequence[str],
+        reason: str,
+        scope_key: str,
+        now_ms: int | None = None,
+    ) -> InstructionAction:
+        if not session_id or not turn_id or not api_request_id:
+            return InstructionAction(False, "missing-correlation-id")
+
+        self._ensure_schema()
+        now = int(time.time() * 1000) if now_ms is None else int(now_ms)
+        expires_at = now + self.ttl_seconds * 1000
+        task = task_id or "root"
+        policy_fingerprint = self._digest([*sorted(policy_names), reason])
+        delivery_key = self._digest(
+            [profile, session_id, task, turn_id, policy_fingerprint, scope_key]
+        )
+
+        try:
+            with self._connect() as connection:
+                connection.execute("BEGIN IMMEDIATE")
+                connection.execute(
+                    "DELETE FROM instruction_deliveries WHERE expires_at_ms <= ?", (now,)
+                )
+                row = connection.execute(
+                    """
+                    SELECT blocked_api_request_id, state
+                    FROM instruction_deliveries
+                    WHERE delivery_key = ?
+                    """,
+                    (delivery_key,),
+                ).fetchone()
+                if row is not None:
+                    blocked_request, state = row
+                    if state == "issued" and blocked_request == api_request_id:
+                        connection.commit()
+                        return InstructionAction(True, "same-api-request")
+                    if state == "issued":
+                        connection.execute(
+                            """
+                            UPDATE instruction_deliveries
+                            SET state = 'acknowledged', acknowledged_api_request_id = ?
+                            WHERE delivery_key = ?
+                            """,
+                            (api_request_id, delivery_key),
+                        )
+                    connection.commit()
+                    return InstructionAction(False, "acknowledged")
+
+                rounds = connection.execute(
+                    """
+                    SELECT COUNT(*)
+                    FROM instruction_deliveries
+                    WHERE profile = ? AND session_id = ? AND task_id = ? AND turn_id = ?
+                      AND expires_at_ms > ?
+                    """,
+                    (profile, session_id, task, turn_id, now),
+                ).fetchone()[0]
+                if rounds >= self.max_rounds:
+                    connection.commit()
+                    return InstructionAction(False, "turn-cap")
+
+                connection.execute(
+                    """
+                    INSERT INTO instruction_deliveries (
+                      delivery_key, profile, session_id, task_id, turn_id,
+                      policy_fingerprint, scope_key, blocked_api_request_id,
+                      acknowledged_api_request_id, state, created_at_ms, expires_at_ms
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, 'issued', ?, ?)
+                    """,
+                    (
+                        delivery_key,
+                        profile,
+                        session_id,
+                        task,
+                        turn_id,
+                        policy_fingerprint,
+                        scope_key,
+                        api_request_id,
+                        now,
+                        expires_at,
+                    ),
+                )
+                connection.commit()
+                return InstructionAction(True, "issued")
+        except (sqlite3.Error, OSError) as exc:
+            raise LedgerError(f"could not update instruction state: {exc}") from exc
+
+    def clear_session(self, session_id: str) -> None:
+        if not session_id:
+            return
+        self._ensure_schema()
+        try:
+            with self._connect() as connection:
+                connection.execute(
+                    "DELETE FROM instruction_deliveries WHERE session_id = ?", (session_id,)
+                )
+        except (sqlite3.Error, OSError) as exc:
+            raise LedgerError(f"could not clear instruction state: {exc}") from exc

package/hermes-plugin/plugin.yaml

@@ -0,0 +1,37 @@
+name: failproofai
+version: 1.0.6-beta.0
+description: Real-time FailproofAI policy enforcement for Hermes
+manifest_version: 2
+api_version: 1
+homepage: https://github.com/FailproofAI/failproofai
+tags: [security, policy, observability]
+provides_hooks:
+  - pre_tool_call
+  - post_tool_call
+  - pre_llm_call
+  - on_session_start
+  - on_session_end
+  - on_session_reset
+  - on_session_finalize
+  - subagent_stop
+config_schema:
+  failure_mode:
+    type: str
+    default: deny
+    description: Block or allow when the local FailproofAI evaluator is unavailable.
+  connect_timeout_ms:
+    type: int
+    default: 250
+    description: Maximum time to connect to the local FailproofAI daemon.
+  evaluation_timeout_ms:
+    type: int
+    default: 12000
+    description: Maximum total time allowed for one policy evaluation.
+  instruction_ttl_seconds:
+    type: int
+    default: 3600
+    description: Maximum lifetime of an instruction-delivery record.
+  max_instruction_rounds:
+    type: int
+    default: 2
+    description: Maximum distinct instruction interruptions in one Hermes turn.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "failproofai",
-  "version": "1.0.5",
+  "version": "1.0.6-beta.0",
   "description": "Observability and enforcement for AI agent harnesses. 39 built-in policies hooked into 12 of them — Claude Code, Codex, Cursor, Hermes, OpenClaw and more — blocking the tool call before it runs. Local dashboard included, no account needed.",
   "bin": {
     "failproofai": "./dist/cli.mjs",
@@ -12,6 +12,7 @@
     "scripts/",
     "lib/",
     "pi-extension/",
+    "hermes-plugin/",
     "openclaw-plugin/",
     ".next/standalone/",
     "dist/",
@@ -80,15 +81,15 @@
     "access": "public"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.123.0",
+    "@anthropic-ai/sdk": "^0.125.0",
     "@mdx-js/mdx": "^3.1.1",
     "@tailwindcss/postcss": "^4.3.1",
     "@tanstack/react-virtual": "^3.14.10",
     "@testing-library/jest-dom": "^7.0.0",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.5",
-    "@types/node": "26.4.1",
-    "@types/react": "19.2.18",
+    "@types/node": "26.5.1",
+    "@types/react": "19.3.0",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.1.0",
     "clsx": "^2.1.1",
@@ -121,15 +122,15 @@
     "browserslist": "4.28.8"
   },
   "optionalDependencies": {
-    "@failproofai/failproofaid-linux-x64": "1.0.5",
-    "@failproofai/failproofaid-linux-arm64": "1.0.5",
-    "@failproofai/failproofaid-darwin-x64": "1.0.5",
-    "@failproofai/failproofaid-darwin-arm64": "1.0.5"
+    "@failproofai/failproofaid-linux-x64": "1.0.6-beta.0",
+    "@failproofai/failproofaid-linux-arm64": "1.0.6-beta.0",
+    "@failproofai/failproofaid-darwin-x64": "1.0.6-beta.0",
+    "@failproofai/failproofaid-darwin-arm64": "1.0.6-beta.0"
   },
   "failproofaidBinaries": {
-    "linux-x64": "5fb4c8a993af9279e46306803c68d6650ea57290bbd7ec92795a7f7b696bb506",
-    "linux-arm64": "21c502073649d9c12710fc2707b9dee08b7ac1528b8544b85a755017c8fdff0e",
-    "darwin-x64": "5e02c2f4887793c64f5553d8d00fd21507f88dce1a6869ca1aca2f6468129373",
-    "darwin-arm64": "65be288a3485ca86869580a036e6c7e9b7b5660a6589143b375586b6c28b5c84"
+    "linux-x64": "38637a91db9a0e5683bbfbfffbba3d65e421960c3135510f23541df5f9d60478",
+    "linux-arm64": "b9a2d9126fb9816b7743ec5b068d36d6515fa3a93fc2e3801fbe3a7a1b2143bf",
+    "darwin-x64": "a06675cd28b3d2f54d45a28f527643841a69006dd68f989dad654806b190948b",
+    "darwin-arm64": "6ef65b956ebff944c38cf2d65b6dc1066384aba7952d7d19c4805c1f1ba593ba"
   }
 }

package/scripts/translate-docs/validate-translation.ts

@@ -11,6 +11,11 @@
  *  - Frontmatter YAML (class A): the model re-emits an inner `"` unescaped into
  *    a double-quoted `title:`/`description:` value, breaking the YAML. This is
  *    the class that failed run 29575781632; `findFrontmatterError` catches it.
+ *  - Empty block (class A2): the model emits a second opening `---`, so the
+ *    block Mintlify reads closes before any key is inside it and the whole
+ *    frontmatter renders as body text. YAML calls a leading `---` a
+ *    document-start marker and parses it clean, so class A is blind to this;
+ *    `mintlifyFrontmatterBlock` is the second view that is not.
  *  - Key parity (class B): the model drops the frontmatter block entirely, or
  *    renames a key. A dropped block is still *valid YAML* (mintlify tolerates
  *    it, deriving the title from the slug), so only comparing against the
@@ -52,6 +57,34 @@ function frontmatterKeys(page: string): string[] | null {
   }
 }
 
+/**
+ * The frontmatter block as MINTLIFY reads it: opened by a first line that is
+ * exactly `---`, closed by the FIRST line after it that is `---` — trailing
+ * spaces or tabs allowed, as `FRONTMATTER_RE` allows them, but never leading
+ * ones: an indented `---` is content, not a delimiter. `null` when the page
+ * does not open with a delimiter at all.
+ *
+ * Deliberately NOT reusing `FRONTMATTER_RE`. That matcher exists to feed
+ * `YAML.parse`, and YAML reads a bare `---` as a document-START marker rather
+ * than as a terminator — so a page beginning `---\n---\ntitle: …` parses there
+ * as a perfectly clean `{title: …}` while Mintlify closes the block on line 2
+ * and renders every key as body text. The reader gets a literal `title: "…"` at
+ * the top of the page and no title on it.
+ *
+ * That is not hypothetical: 102 published pages across seven locales shipped
+ * exactly that way, invisible to every other check in this file, because both
+ * of them asked YAML. The two views have to be compared, never shared.
+ */
+function mintlifyFrontmatterBlock(page: string): string | null {
+  const lines = page.split(/\r?\n/);
+  if (lines[0] !== "---") return null;
+  const close = lines.findIndex(
+    (line, i) => i > 0 && /^---[ \t]*$/.test(line),
+  );
+  if (close < 0) return null;
+  return lines.slice(1, close).join("\n");
+}
+
 /**
  * A ±2-line window around `line` (1-based), the failing line prefixed `> ` and
  * its neighbours `  `. Empty string when `line` is undefined.
@@ -93,6 +126,21 @@ export async function findTranslationError(
     );
   }
 
+  // Class A2: a block that is EMPTY as Mintlify delimits it. A stray opening
+  // delimiter (`---\n---\ntitle: …`) is the shape that does this, and it is
+  // invisible to everything above — see `mintlifyFrontmatterBlock`. Checked for
+  // every source shape, like the YAML above: the model adding this to a
+  // frontmatter-less page breaks that page just as thoroughly.
+  const mintlifyBlock = mintlifyFrontmatterBlock(rendered);
+  if (mintlifyBlock !== null && mintlifyBlock.trim() === "") {
+    return (
+      "The YAML frontmatter block is empty. The page opens with `---` and the " +
+      "very next line is `---` again, which closes the block before any key is " +
+      "in it — every `title:`/`description:`/`icon:` line below then renders as " +
+      "body text and the page has no title. Emit exactly one opening `---`."
+    );
+  }
+
   const sourceKeys = frontmatterKeys(source);
   if (sourceKeys) {
     // The source has frontmatter, so the translation must carry the same keys.

package/src/hooks/handler.ts

@@ -102,6 +102,21 @@ export interface HookEventOutcome {
   exitCode: number;
   stdout: string;
   stderr: string;
+  /**
+   * Structured policy metadata for in-process adapters. Existing shell-hook
+   * callers intentionally ignore this and keep consuming stdout/stderr.
+   */
+  evaluation?: HookEvaluationSummary;
+}
+
+export interface HookEvaluationSummary {
+  decision: "allow" | "deny" | "instruct";
+  policyName: string | null;
+  policyNames: string[];
+  reason: string | null;
+  matchedPolicies: string[];
+  durationMs: number;
+  toolName: string | null;
 }
 
 export interface EvaluateHookEventOptions {
@@ -757,7 +772,20 @@ export async function evaluateHookEvent(
       }
     }
 
-    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 as string) ?? null,
+      },
+    };
   } finally {
     if (opts?.awaitTelemetryFlush ?? true) {
       // Await any un-awaited (`void trackHookEvent(...)`) events fired during