entroly-openclaw 1.0.61 → 1.0.63

package/README.md

@@ -22,7 +22,7 @@ Install the Python engine, then install the plugin from OpenClaw's official
 ClawHub registry:
 
 ```bash
-pip install "entroly>=1.0.57"
+pip install "entroly>=1.0.63"
 openclaw plugins install clawhub:entroly-openclaw
 openclaw plugins enable entroly
 ```
@@ -37,7 +37,7 @@ openclaw plugins enable entroly
 From an Entroly source checkout:
 
 ```bash
-pip install "entroly>=1.0.57"
+pip install "entroly>=1.0.63"
 openclaw plugins install ./integrations/openclaw
 openclaw plugins enable entroly
 ```
@@ -65,7 +65,7 @@ After the first agent turn, run `/entroly-context` in any connected channel to
 see the estimated before/after context size, reduction, warnings, and receipt.
 Run `/entroly-context doctor` to verify the configured Python executable and
 local JSONL bridge before inviting users onto the Gateway. The plugin requires
-the Entroly 1.0.57 bridge v2 protocol; doctor reports an actionable upgrade
+the Entroly 1.0.63 bridge v2 protocol; doctor reports an actionable upgrade
 instead of accepting an older, incompatible Python installation.
 
 OpenClaw's resolved prompt token budget is authoritative. When an older or
@@ -100,6 +100,54 @@ actionable warning instead of risking a provider overflow. Explicit OpenClaw
 budgets always win, followed by the operator's `fallbackTokenBudget`; automatic
 registry discovery is used only when neither is available.
 
+## Optional proof-guided exact recovery
+
+Default behavior performs local context assembly only and makes no additional
+model call. To let Entroly verify a draft, recover exact omitted messages, and
+ask OpenClaw for a bounded revision, opt in explicitly:
+
+```json5
+{
+  plugins: {
+    slots: { contextEngine: "entroly" },
+    entries: {
+      entroly: {
+        hooks: { allowConversationAccess: true },
+        config: {
+          proofGuidedRecovery: true,
+          proofGuidedMaxRounds: 2,
+          proofGuidedRecoveryTokens: 1200,
+          proofGuidedMaxMessages: 3
+        }
+      }
+    }
+  }
+}
+```
+
+`proofGuidedMaxRounds` includes the first response, so the default maximum of
+two allows at most one additional model call. Entroly never receives provider
+credentials and never calls the provider itself: it returns an idempotent
+revision request to OpenClaw, which keeps its normal provider routing and
+billing behavior. The retry contains exact recovered message text and SHA-256
+commitments, not a generated summary.
+
+The local bridge checks the draft with EICV and the context firewall. If a
+claim is unsupported, it either identifies exact omitted evidence for the
+bounded revision or supplies a safer verified output. If bridge verification
+fails or model output is unsafe, the delivery hook substitutes a clear withheld
+response instead of silently passing unverified text. `/entroly-context` shows
+the proof status, attempt count, and local audit artifact ID.
+
+This feature requires a current OpenClaw build that exposes `llm_output`,
+`before_agent_finalize`, and `reply_payload_sending`, plus the explicit
+`allowConversationAccess` grant shown above. Verify registration after restart:
+
+```bash
+openclaw plugins inspect entroly --runtime --json
+openclaw plugins doctor
+```
+
 ## Reproduce the evidence-pinning control
 
 ```bash

package/engine.js

@@ -45,6 +45,7 @@ function statusSnapshot(status) {
     "context_window",
     "context_output_reserve",
     "context_safety_tokens",
+    "proof_guided_attempts",
   ];
   const booleanFields = ["changed", "provider_independent"];
   const stringFields = [
@@ -58,6 +59,8 @@ function statusSnapshot(status) {
     "model",
     "provider_hint",
     "assembly_strategy",
+    "proof_guided_status",
+    "proof_guided_audit_artifact_id",
     "error",
   ];
   for (const field of numericFields) {
@@ -385,6 +388,17 @@ export function formatEntrolyStatus(status) {
     );
   }
   if (status.receipt_id) lines.push(`Receipt: ${boundedString(status.receipt_id, 160)}`);
+  if (status.proof_guided_status) {
+    lines.push(
+      `Proof-guided recovery: ${boundedString(status.proof_guided_status, 160)}`,
+      `Proof model attempts: ${Number(status.proof_guided_attempts ?? 0).toLocaleString()}`,
+    );
+  }
+  if (status.proof_guided_audit_artifact_id) {
+    lines.push(
+      `Proof audit: ${boundedString(status.proof_guided_audit_artifact_id, 160)}`,
+    );
+  }
   if (status.warnings?.length) {
     lines.push(`Warnings: ${status.warnings.map((warning) => safeDiagnostic(warning)).join(" | ")}`);
   }
@@ -418,6 +432,7 @@ export function createEntrolyContextEngine({
   config = {},
   logger = console,
   statusBySession = new Map(),
+  proofStateBySession = new Map(),
   maxStatusSessions = 512,
 }) {
   if (typeof delegateCompaction !== "function") {
@@ -548,6 +563,7 @@ export function createEntrolyContextEngine({
           context_safety_tokens:
             assemblyRuntime.runtimeMetadata.context_discovery?.safety_tokens,
         });
+        proofStateBySession.delete(sessionId);
         return {
           messages: sourceMessages,
           estimatedTokens: estimateTokens(sourceMessages),
@@ -627,7 +643,36 @@ export function createEntrolyContextEngine({
             "Entroly bridge wrote a receipt without the required acceptance handshake",
           );
         }
-        storeStatus(sessionId, result);
+        if (config.proofGuidedRecovery === true) {
+          const existing = proofStateBySession.get(sessionId);
+          if (!existing || existing.prompt !== prompt || existing.disabled) {
+            proofStateBySession.set(sessionId, {
+              prompt,
+              workspaceDir: config.workspaceDir,
+              sourceMessages: structuredClone(sourceMessages),
+              assembledMessages: structuredClone(result.messages),
+              recoveredMessages: [],
+              attempts: 0,
+              runId: null,
+              lastOutputSha256: null,
+              lastProofResult: null,
+              retryIssued: false,
+              disabled: false,
+            });
+          }
+          while (proofStateBySession.size > statusLimit) {
+            proofStateBySession.delete(proofStateBySession.keys().next().value);
+          }
+        } else {
+          proofStateBySession.delete(sessionId);
+        }
+        storeStatus(sessionId, {
+          ...result,
+          proof_guided_status:
+            config.proofGuidedRecovery === true ? "armed" : "disabled",
+          proof_guided_attempts:
+            proofStateBySession.get(sessionId)?.attempts ?? 0,
+        });
         return {
           messages: result.messages,
           estimatedTokens: result.estimated_tokens,

package/index.js

@@ -9,6 +9,7 @@ import {
   formatEntrolyDoctor,
   formatEntrolyStatus,
 } from "./engine.js";
+import { createProofGuidedHooks } from "./proof-hooks.js";
 
 export default definePluginEntry({
   id: "entroly",
@@ -22,6 +23,7 @@ export default definePluginEntry({
       logger: api.logger,
     });
     const statusBySession = new Map();
+    const proofStateBySession = new Map();
     api.registerContextEngine("entroly", (factoryContext) => {
       latestWorkspaceDir = factoryContext.workspaceDir;
       return createEntrolyContextEngine({
@@ -31,8 +33,27 @@ export default definePluginEntry({
         config: { ...config, workspaceDir: factoryContext.workspaceDir },
         logger: api.logger,
         statusBySession,
+        proofStateBySession,
       });
     });
+    if (config.proofGuidedRecovery === true) {
+      if (typeof api.on !== "function") {
+        api.logger.error?.(
+          "entroly: this OpenClaw host does not expose typed proof-guided hooks; disable proofGuidedRecovery or upgrade OpenClaw",
+        );
+      } else {
+        const proofHooks = createProofGuidedHooks({
+          bridge,
+          config,
+          logger: api.logger,
+          proofStateBySession,
+          statusBySession,
+        });
+        api.on("llm_output", proofHooks.onLlmOutput);
+        api.on("before_agent_finalize", proofHooks.onBeforeAgentFinalize);
+        api.on("reply_payload_sending", proofHooks.onReplyPayloadSending);
+      }
+    }
     api.registerCommand({
       name: "entroly-context",
       description: "Show Entroly context savings or run `doctor`.",

package/openclaw.plugin.json

@@ -4,7 +4,7 @@
     "onStartup": true
   },
   "name": "Entroly Context Engine",
-  "description": "Provider-independent context assembly for every OpenClaw model route, with protected blocks, recovery delegation, and local audit receipts.",
+  "description": "Provider-independent context engineering for every OpenClaw model route, with protected blocks, recovery delegation, and local audit receipts.",
   "icon": "https://raw.githubusercontent.com/juyterman1000/entroly/main/docs/assets/entroly_wordmark.svg",
   "configSchema": {
     "type": "object",
@@ -63,6 +63,28 @@
       "evidencePinning": {
         "type": "boolean",
         "default": true
+      },
+      "proofGuidedRecovery": {
+        "type": "boolean",
+        "default": false
+      },
+      "proofGuidedMaxRounds": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 4,
+        "default": 2
+      },
+      "proofGuidedRecoveryTokens": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 100000,
+        "default": 1200
+      },
+      "proofGuidedMaxMessages": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 16,
+        "default": 3
       }
     }
   },
@@ -110,6 +132,22 @@
     "evidencePinning": {
       "label": "Query-Aware Evidence Pinning",
       "help": "Keep older messages that match the current request verbatim when they fit the bounded evidence reserve."
+    },
+    "proofGuidedRecovery": {
+      "label": "Proof-Guided Recovery",
+      "help": "Opt in to local output verification and at most the configured number of OpenClaw revision passes using exact recovered evidence. Requires hooks.allowConversationAccess=true because it inspects model input and output."
+    },
+    "proofGuidedMaxRounds": {
+      "label": "Maximum Proof Rounds",
+      "help": "Hard cap on model attempts, including the first response. Additional paid calls occur only when Proof-Guided Recovery is explicitly enabled."
+    },
+    "proofGuidedRecoveryTokens": {
+      "label": "Recovery Token Budget",
+      "help": "Maximum estimated exact-evidence tokens recovered for one revision decision."
+    },
+    "proofGuidedMaxMessages": {
+      "label": "Recovery Message Limit",
+      "help": "Maximum exact omitted messages appended to one revision instruction."
     }
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "entroly-openclaw",
-  "version": "1.0.61",
-  "description": "Provider-independent, auditable context optimization for every OpenClaw model route",
+  "version": "1.0.63",
+  "description": "Provider-independent, auditable context engineering for every OpenClaw model route",
   "type": "module",
   "license": "Apache-2.0",
   "homepage": "https://github.com/juyterman1000/entroly#entroly-for-openclaw",
@@ -13,6 +13,16 @@
   "bugs": {
     "url": "https://github.com/juyterman1000/entroly/issues"
   },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "ai-agents",
+    "context-engineering",
+    "context-compression",
+    "context-optimization",
+    "context-receipts",
+    "model-context-protocol"
+  ],
   "engines": {
     "node": ">=22.19"
   },
@@ -20,12 +30,13 @@
     "bridge-client.js",
     "engine.js",
     "index.js",
+    "proof-hooks.js",
     "openclaw.plugin.json",
     "README.md"
   ],
   "scripts": {
     "test": "node --test test/*.test.js",
-    "check": "node --check bridge-client.js && node --check engine.js && node --check index.js",
+    "check": "node --check bridge-client.js && node --check engine.js && node --check proof-hooks.js && node --check index.js",
     "pack:check": "npm pack --dry-run"
   },
   "peerDependencies": {

package/proof-hooks.js

@@ -0,0 +1,198 @@
+import { createHash } from "node:crypto";
+
+import { ENTROLY_BRIDGE_SCHEMA } from "./bridge-client.js";
+
+function sha256(value) {
+  return createHash("sha256").update(String(value), "utf8").digest("hex");
+}
+
+function safeDiagnostic(value, limit = 400) {
+  return String(value?.message ?? value ?? "unknown error")
+    .replace(/\s+/g, " ")
+    .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED]")
+    .replace(
+      /\b(api[_-]?key|authorization|password|secret|token)\b\s*[:=]\s*["']?[^\s,;"']+/gi,
+      "$1=[REDACTED]",
+    )
+    .slice(0, limit);
+}
+
+function positiveInteger(value, fallback, maximum) {
+  return typeof value === "number" &&
+    Number.isInteger(value) &&
+    value > 0 &&
+    value <= maximum
+    ? value
+    : fallback;
+}
+
+function validateProofResult(result) {
+  if (
+    !result ||
+    result.ok !== true ||
+    result.schema_version !== ENTROLY_BRIDGE_SCHEMA ||
+    result.provider_call_performed !== false ||
+    result.local_only !== true ||
+    typeof result.status !== "string" ||
+    typeof result.verified_output !== "string" ||
+    !Array.isArray(result.recovered_messages) ||
+    typeof result.audit_artifact_id !== "string"
+  ) {
+    throw new Error("Entroly bridge returned an invalid proof-guided result");
+  }
+  if (
+    result.status === "retry_with_exact_evidence" &&
+    (typeof result.retry_instruction !== "string" || !result.retry_instruction.trim())
+  ) {
+    throw new Error("Entroly bridge omitted the exact-evidence retry instruction");
+  }
+  return result;
+}
+
+function mergeRecoveredMessages(existing, recovered) {
+  const seen = new Set(existing.map((message) => sha256(JSON.stringify(message))));
+  const merged = [...existing];
+  for (const message of recovered) {
+    const fingerprint = sha256(JSON.stringify(message));
+    if (seen.has(fingerprint)) continue;
+    seen.add(fingerprint);
+    merged.push(message);
+  }
+  return merged;
+}
+
+export function createProofGuidedHooks({
+  bridge,
+  config = {},
+  logger = console,
+  proofStateBySession = new Map(),
+  statusBySession = new Map(),
+}) {
+  const maxRounds = positiveInteger(config.proofGuidedMaxRounds, 2, 4);
+  const recoveryTokenBudget = positiveInteger(
+    config.proofGuidedRecoveryTokens,
+    1200,
+    100000,
+  );
+  const maxRecoveryMessages = positiveInteger(
+    config.proofGuidedMaxMessages,
+    3,
+    16,
+  );
+
+  return {
+    async onLlmOutput(event) {
+      const state = proofStateBySession.get(event?.sessionId);
+      if (!state || state.disabled || state.attempts >= maxRounds) return;
+      const output = Array.isArray(event.assistantTexts)
+        ? event.assistantTexts.filter((value) => typeof value === "string").join("\n\n")
+        : "";
+      if (!output.trim()) return;
+      const outputSha = sha256(output);
+      if (state.lastOutputSha256 === outputSha && state.lastProofResult) return;
+      try {
+        const result = validateProofResult(
+          await bridge.request({
+            operation: "verify_proof_guided_output",
+            session_id: event.sessionId,
+            run_id: event.runId,
+            round_index: state.attempts,
+            source_messages: state.sourceMessages,
+            assembled_messages: state.assembledMessages,
+            recovered_messages: state.recoveredMessages,
+            model_output: output,
+            workspace_dir: state.workspaceDir,
+            profile: config.proofGuidedProfile ?? "rag",
+            recovery_token_budget: recoveryTokenBudget,
+            max_recovery_messages: maxRecoveryMessages,
+          }),
+        );
+        state.attempts += 1;
+        state.runId = event.runId;
+        state.lastOutputSha256 = outputSha;
+        state.lastProofResult = result;
+        state.recoveredMessages = mergeRecoveredMessages(
+          state.recoveredMessages,
+          result.recovered_messages,
+        );
+        state.retryIssued = false;
+        statusBySession.set(event.sessionId, {
+          ...(statusBySession.get(event.sessionId) ?? {}),
+          proof_guided_status: result.status,
+          proof_guided_attempts: state.attempts,
+          proof_guided_audit_artifact_id: result.audit_artifact_id,
+        });
+      } catch (error) {
+        state.disabled = true;
+        state.error = safeDiagnostic(error);
+        state.runId = event?.runId;
+        state.lastProofResult = {
+          status: "verification_error",
+          verified_output:
+            "Entroly withheld this response because local proof verification failed. " +
+            "Review the OpenClaw plugin log and retry after resolving the reported error.",
+          changed: true,
+          recovered_messages: [],
+          audit_artifact_id: "",
+        };
+        statusBySession.set(event.sessionId, {
+          ...(statusBySession.get(event.sessionId) ?? {}),
+          proof_guided_status: "verification_error",
+          proof_guided_attempts: state.attempts,
+          error: state.error,
+        });
+        logger.warn?.(
+          `entroly: proof-guided verification failed; delivery will be withheld: ${state.error}`,
+        );
+      }
+    },
+
+    async onBeforeAgentFinalize(event) {
+      const state = proofStateBySession.get(event?.sessionId);
+      const result = state?.lastProofResult;
+      if (
+        !state ||
+        !result ||
+        state.runId !== event?.runId ||
+        result.status !== "retry_with_exact_evidence" ||
+        state.attempts >= maxRounds ||
+        state.retryIssued
+      ) {
+        return;
+      }
+      state.retryIssued = true;
+      return {
+        action: "revise",
+        reason: "Entroly found unsupported claims and recovered exact omitted evidence.",
+        retry: {
+          instruction: result.retry_instruction,
+          idempotencyKey: `entroly-proof-${sha256(
+            `${event.runId}:${result.audit_artifact_id}:${state.attempts}`,
+          ).slice(0, 24)}`,
+          maxAttempts: 1,
+        },
+      };
+    },
+
+    async onReplyPayloadSending(event) {
+      const sessionId = event?.usageState?.sessionId;
+      const state = sessionId ? proofStateBySession.get(sessionId) : undefined;
+      const result = state?.lastProofResult;
+      if (
+        !state ||
+        !result ||
+        (event?.runId && state.runId !== event.runId) ||
+        result.changed !== true ||
+        typeof event?.payload?.text !== "string"
+      ) {
+        return;
+      }
+      return {
+        payload: {
+          ...event.payload,
+          text: result.verified_output,
+        },
+      };
+    },
+  };
+}