entroly-openclaw 1.0.53 → 1.0.57

package/README.md

@@ -3,26 +3,41 @@
 Entroly provides budget-aware, auditable context assembly for OpenClaw while
 leaving OpenClaw's persisted transcript untouched.
 
+**Every OpenClaw provider benefits from the same Entroly context engine.**
+OpenClaw continues to own provider selection, authentication, model failover,
+and wire formats. Entroly operates once on OpenClaw's normalized messages
+before each model run, whether the route is OpenAI, Anthropic, Gemini,
+Nemotron, OpenRouter, Ollama, or a private/custom provider.
+
 Unlike uniform history summarization, Entroly scores older messages against the
 current request, reserves a bounded part of the context budget for matching
 evidence, and keeps evidence messages verbatim when they fit. Lower-value
 history is compressed around those evidence pins. The receipt records every
-score, matched query term, allocation, and transformation.
+score, query-term match count, allocation, and transformation without storing
+the request text or matched terms.
 
-## Install
+## Install from ClawHub
 
-After the package is published:
+Install the Python engine, then install the plugin from OpenClaw's official
+ClawHub registry:
 
 ```bash
-pip install entroly
-openclaw plugins install entroly-openclaw
+pip install "entroly>=1.0.57"
+openclaw plugins install clawhub:entroly-openclaw
+openclaw plugins enable entroly
+```
+
+The npm-only fallback remains available as:
+
+```bash
+openclaw plugins install npm:entroly-openclaw
 openclaw plugins enable entroly
 ```
 
 From an Entroly source checkout:
 
 ```bash
-pip install entroly
+pip install "entroly>=1.0.57"
 openclaw plugins install ./integrations/openclaw
 openclaw plugins enable entroly
 ```
@@ -49,7 +64,27 @@ openclaw plugins doctor
 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.
+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
+instead of accepting an older, incompatible Python installation.
+
+OpenClaw's resolved prompt token budget is authoritative. Entroly never guesses
+a context window from the provider name. For a custom model whose limit
+OpenClaw cannot resolve, configure that model's context window in OpenClaw or
+set an explicit operator-approved fallback:
+
+```json5
+{
+  plugins: {
+    entries: {
+      entroly: { config: { fallbackTokenBudget: 32768 } }
+    }
+  }
+}
+```
+
+Without either budget, Entroly returns the exact original context with an
+actionable warning instead of risking a provider overflow.
 
 ## Reproduce the evidence-pinning control
 
@@ -63,16 +98,51 @@ uniform budget compression at the same estimated token budget. See the
 no model calls and does not claim downstream task accuracy.
 
 Receipts are written under `<workspace>/.entroly/receipts/openclaw/` unless
-`receiptDir` is configured. They record per-message hashes and decisions,
-estimated tokens, reduction, warnings, and whether context changed. The
-original content remains recoverable from OpenClaw's unchanged transcript.
+`receiptDir` is configured. They record keyed per-message digests and decisions,
+estimated tokens, reduction, warnings, and whether context changed. Query text
+and matched terms are not persisted; only lengths and counts remain. Each
+append-only proposal has a cryptographic nonce and immutable payload digest. It
+is first marked `proposed`, then atomically marked `accepted` only after the
+plugin validates the returned message structure and reveals its precommitted
+256-bit challenge. Entroly stores only a host-commit digest plus an HMAC
+signature from a private key outside the workspace receipt; it never persists
+the challenge secret. Acceptance proves plugin validation, not provider
+delivery. Content digests are HMAC-keyed as well, preventing offline guesses of
+low-entropy user prompts from a receipt alone.
+The original content remains recoverable from OpenClaw's unchanged transcript.
 Entroly makes no remote calls in this path.
 
+The signing key is initialized atomically outside the workspace receipt store
+under the user state directory (`%LOCALAPPDATA%/Entroly` on Windows or
+`$XDG_STATE_HOME/entroly` on Unix). Controlled deployments may set
+`ENTROLY_OPENCLAW_RECEIPT_KEY_FILE` to an absolute protected path. Entroly
+quarantines an interrupted empty initialization artifact; a non-empty corrupt
+key fails open with its exact recovery path instead of silently rotating and
+invalidating earlier receipt signatures. `/entroly-context doctor` checks this
+key lifecycle as part of bridge readiness.
+
+The receipt directory defaults to private `0700` permissions and receipt files
+to `0600` on Unix; Windows uses the workspace ACL. Entroly never auto-deletes
+audit history. The default append-only quota is 512 files or 64 MiB, whichever
+comes first. At the limit, assembly fails open with an actionable message;
+archive receipts or raise `receiptMaxFiles` / `receiptMaxBytes` explicitly.
+
 ## Safety contract
 
 - System and developer messages are never modified.
-- Structured message content is never modified.
+- Signed text, thinking/reasoning, images, tool calls, tool-result metadata,
+  opaque provider signatures, and unknown content blocks are never modified.
+- Only unsigned text fields in older normalized messages are compressible;
+  provider/model/usage metadata cannot change selection or allocation.
 - Recent messages are preserved verbatim.
 - Bridge errors return the exact original message list.
+- A malformed host message envelope is surfaced as an error; it is never
+  coerced into an empty prompt.
+- If the minimum safe normalized context cannot fit the host budget, Entroly
+  returns the exact original context and requests OpenClaw recovery.
 - Entroly does not rewrite the OpenClaw transcript or claim persistent
   compaction.
+- `/compact` and provider-overflow recovery delegate to OpenClaw's native
+  compaction runtime, preserving its provider-aware retry behavior.
+- Active OpenClaw memory guidance remains present when Entroly is selected as
+  the context engine.

package/bridge-client.js

@@ -1,17 +1,36 @@
 import { spawn } from "node:child_process";
 import readline from "node:readline";
 
+export const ENTROLY_BRIDGE_SCHEMA = "entroly.openclaw.bridge.v2";
+
+export function validateBridgeHealth(result) {
+  if (
+    !result ||
+    result.ok !== true ||
+    result.schema_version !== ENTROLY_BRIDGE_SCHEMA ||
+    result.provider_independent !== true ||
+    result.receipt_commit_protocol !== "two_phase"
+  ) {
+    throw new Error(
+      "Incompatible Entroly Python bridge; install entroly>=1.0.57 with `python -m pip install -U entroly`",
+    );
+  }
+  return result;
+}
+
 export class EntrolyBridgeClient {
   constructor({
     pythonCommand = "python",
     timeoutMs = 5000,
     logger = console,
     spawnProcess = spawn,
+    environment = process.env,
   } = {}) {
     this.pythonCommand = pythonCommand;
     this.timeoutMs = timeoutMs;
     this.logger = logger;
     this.spawnProcess = spawnProcess;
+    this.environment = environment;
     this.nextId = 1;
     this.pending = new Map();
     this.process = undefined;
@@ -24,7 +43,11 @@ export class EntrolyBridgeClient {
     const child = this.spawnProcess(
       this.pythonCommand,
       ["-m", "entroly.openclaw_bridge", "--jsonl"],
-      { stdio: ["pipe", "pipe", "pipe"], windowsHide: true },
+      {
+        stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
+        env: this.environment,
+      },
     );
     this.process = child;
     const lines = readline.createInterface({ input: child.stdout });
@@ -61,8 +84,15 @@ export class EntrolyBridgeClient {
     });
   }
 
-  health() {
-    return this.request({ operation: "health" });
+  async health({ workspaceDir, receiptDir, writeReceipts = true } = {}) {
+    return validateBridgeHealth(
+      await this.request({
+        operation: "health",
+        workspace_dir: workspaceDir,
+        receipt_dir: receiptDir,
+        write_receipt: writeReceipts,
+      }),
+    );
   }
 
   #onLine(line) {

package/engine.js

@@ -1,4 +1,269 @@
-const DEFAULT_TOKEN_BUDGET = 50_000;
+import { createHash, randomBytes } from "node:crypto";
+
+import { ENTROLY_BRIDGE_SCHEMA } from "./bridge-client.js";
+
+const PROVIDER_MODE = "openclaw_managed";
+
+function positiveInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0
+    ? value
+    : undefined;
+}
+
+function boundedString(value, limit = 256) {
+  return typeof value === "string" && value.trim()
+    ? value.trim().slice(0, limit)
+    : null;
+}
+
+function safeDiagnostic(value, limit = 400) {
+  let diagnostic = String(value?.message ?? value ?? "unknown error")
+    .replace(/\s+/g, " ")
+    .trim();
+  diagnostic = diagnostic
+    .replace(
+      /\bAuthorization\s*:\s*(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi,
+      "Authorization: [REDACTED]",
+    )
+    .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]",
+    )
+    .replace(/\b(?:sk|gh[opusr])[-_][A-Za-z0-9_-]{8,}\b/gi, "[REDACTED]");
+  return diagnostic.slice(0, limit) || "unknown error";
+}
+
+function statusSnapshot(status) {
+  const snapshot = { ok: status?.ok === true };
+  const numericFields = [
+    "estimated_tokens",
+    "source_tokens",
+    "tokens_saved",
+    "evidence_pinned",
+    "evidence_pin_blocked",
+  ];
+  const booleanFields = ["changed", "provider_independent"];
+  const stringFields = [
+    "schema_version",
+    "receipt_id",
+    "provider_mode",
+    "budget_source",
+    "model",
+    "provider_hint",
+    "assembly_strategy",
+    "error",
+  ];
+  for (const field of numericFields) {
+    if (typeof status?.[field] === "number" && Number.isFinite(status[field])) {
+      snapshot[field] = status[field];
+    }
+  }
+  for (const field of booleanFields) {
+    if (typeof status?.[field] === "boolean") snapshot[field] = status[field];
+  }
+  for (const field of stringFields) {
+    if (status?.[field] === undefined || status?.[field] === null) continue;
+    const value =
+      field === "error"
+        ? safeDiagnostic(status?.[field])
+        : boundedString(status?.[field], field === "receipt_id" ? 160 : 256);
+    if (value !== null) snapshot[field] = value;
+  }
+  if (Array.isArray(status?.warnings)) {
+    snapshot.warnings = status.warnings
+      .slice(0, 8)
+      .map((warning) => safeDiagnostic(warning));
+  }
+  return snapshot;
+}
+
+function validateReceiptCommit(result, proposal) {
+  if (
+    !result ||
+    result.ok !== true ||
+    result.schema_version !== ENTROLY_BRIDGE_SCHEMA ||
+    result.committed !== true ||
+    result.receipt_id !== proposal.receiptId ||
+    result.proposal_id !== proposal.proposalId ||
+    result.proposal_sha256 !== proposal.proposalSha256 ||
+    result.receipt_path !== proposal.receiptPath ||
+    result.acceptance_commit_sha256 !== proposal.acceptanceCommitSha256
+  ) {
+    throw new Error("Entroly bridge did not acknowledge the validated receipt");
+  }
+}
+
+function sha256(value) {
+  return createHash("sha256").update(value, "utf8").digest("hex");
+}
+
+function resolveAssemblyRuntime({ tokenBudget, model, runtimeSettings, fallbackTokenBudget }) {
+  const explicitBudget = positiveInteger(tokenBudget);
+  const runtimeBudget = positiveInteger(runtimeSettings?.limits?.promptTokenBudget);
+  const fallbackCandidate = positiveInteger(fallbackTokenBudget);
+  const configuredFallback =
+    fallbackCandidate !== undefined && fallbackCandidate >= 1024
+      ? fallbackCandidate
+      : undefined;
+  const requestedModel = boundedString(runtimeSettings?.model?.requested);
+  const resolvedModel =
+    boundedString(runtimeSettings?.model?.resolved) ?? requestedModel ?? boundedString(model);
+  const runtimeMetadata = {
+    schema_version: runtimeSettings?.schemaVersion === 1 ? 1 : null,
+    runtime: {
+      host: boundedString(runtimeSettings?.runtime?.host, 64),
+      mode: boundedString(runtimeSettings?.runtime?.mode, 64),
+      harness_id: boundedString(runtimeSettings?.runtime?.harnessId, 128),
+      runtime_id: boundedString(runtimeSettings?.runtime?.runtimeId, 128),
+    },
+    model: {
+      requested: requestedModel ?? boundedString(model),
+      resolved: resolvedModel,
+      provider: boundedString(runtimeSettings?.model?.provider, 128),
+      family: boundedString(runtimeSettings?.model?.family, 128),
+    },
+    limits: {
+      prompt_token_budget: runtimeBudget ?? null,
+      max_output_tokens: positiveInteger(runtimeSettings?.limits?.maxOutputTokens) ?? null,
+    },
+  };
+
+  if (explicitBudget !== undefined) {
+    return {
+      tokenBudget: explicitBudget,
+      budgetSource: "openclaw_token_budget",
+      model: resolvedModel,
+      runtimeMetadata,
+    };
+  }
+  if (runtimeBudget !== undefined) {
+    return {
+      tokenBudget: runtimeBudget,
+      budgetSource: "openclaw_runtime_settings",
+      model: resolvedModel,
+      runtimeMetadata,
+    };
+  }
+  if (configuredFallback !== undefined) {
+    return {
+      tokenBudget: configuredFallback,
+      budgetSource: "operator_fallback",
+      model: resolvedModel,
+      runtimeMetadata,
+    };
+  }
+  return {
+    tokenBudget: undefined,
+    budgetSource: "missing",
+    model: resolvedModel,
+    runtimeMetadata,
+  };
+}
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function isCompressibleTextBlock(block) {
+  return Boolean(
+    block &&
+      typeof block === "object" &&
+      !Array.isArray(block) &&
+      block.type === "text" &&
+      typeof block.text === "string" &&
+      Object.keys(block).every((key) => key === "type" || key === "text"),
+  );
+}
+
+function validateAssemblyResult(result, sourceMessages, preserveLastN) {
+  if (
+    !result ||
+    result.ok !== true ||
+    result.schema_version !== ENTROLY_BRIDGE_SCHEMA
+  ) {
+    throw new Error("Entroly bridge did not return a successful assembly result");
+  }
+  if (
+    !Array.isArray(result.messages) ||
+    result.messages.length !== sourceMessages.length ||
+    !result.messages.every(
+      (message) => message && typeof message === "object" && !Array.isArray(message),
+    )
+  ) {
+    throw new Error("Entroly bridge returned an invalid or incomplete message list");
+  }
+  if (
+    typeof result.estimated_tokens !== "number" ||
+    !Number.isFinite(result.estimated_tokens) ||
+    result.estimated_tokens < 0
+  ) {
+    throw new Error("Entroly bridge returned an invalid token estimate");
+  }
+
+  const recentStart = Math.max(0, sourceMessages.length - preserveLastN);
+  for (let index = 0; index < sourceMessages.length; index += 1) {
+    const source = sourceMessages[index];
+    const assembled = result.messages[index];
+    if (source.role !== assembled.role) {
+      throw new Error(`Entroly bridge changed message role at index ${index}`);
+    }
+
+    const { content: sourceContent, ...sourceMetadata } = source;
+    const { content: assembledContent, ...assembledMetadata } = assembled;
+    if (canonicalJson(sourceMetadata) !== canonicalJson(assembledMetadata)) {
+      throw new Error(`Entroly bridge changed message metadata at index ${index}`);
+    }
+
+    const exactMessage =
+      source.role === "system" || source.role === "developer" || index >= recentStart;
+    if (exactMessage) {
+      if (canonicalJson(sourceContent) !== canonicalJson(assembledContent)) {
+        throw new Error(`Entroly bridge changed protected message at index ${index}`);
+      }
+      continue;
+    }
+
+    if (typeof sourceContent === "string") {
+      if (typeof assembledContent !== "string") {
+        throw new Error(`Entroly bridge changed text content shape at index ${index}`);
+      }
+      continue;
+    }
+    if (!Array.isArray(sourceContent) || !Array.isArray(assembledContent)) {
+      if (canonicalJson(sourceContent) !== canonicalJson(assembledContent)) {
+        throw new Error(`Entroly bridge changed opaque content at index ${index}`);
+      }
+      continue;
+    }
+    if (sourceContent.length !== assembledContent.length) {
+      throw new Error(`Entroly bridge changed content block count at index ${index}`);
+    }
+    for (let blockIndex = 0; blockIndex < sourceContent.length; blockIndex += 1) {
+      const sourceBlock = sourceContent[blockIndex];
+      const assembledBlock = assembledContent[blockIndex];
+      if (isCompressibleTextBlock(sourceBlock)) {
+        if (!isCompressibleTextBlock(assembledBlock)) {
+          throw new Error(
+            `Entroly bridge changed text block shape at index ${index}:${blockIndex}`,
+          );
+        }
+      } else if (canonicalJson(sourceBlock) !== canonicalJson(assembledBlock)) {
+        throw new Error(
+          `Entroly bridge changed opaque content block at index ${index}:${blockIndex}`,
+        );
+      }
+    }
+  }
+  return result;
+}
 
 function estimateTokens(messages) {
   return Math.ceil(JSON.stringify(messages).length / 4);
@@ -9,7 +274,11 @@ export function formatEntrolyStatus(status) {
     return "Entroly: no context assembly has completed for this session yet.";
   }
   if (!status.ok) {
-    return `Entroly: last assembly failed open to the original context.\nReason: ${status.error}`;
+    return [
+      "Entroly: last assembly failed open to the original context.",
+      "Provider routing remains OpenClaw-managed.",
+      `Reason: ${safeDiagnostic(status.error)}`,
+    ].join("\n");
   }
   const source = status.source_tokens ?? 0;
   const assembled = status.estimated_tokens ?? source;
@@ -17,6 +286,8 @@ export function formatEntrolyStatus(status) {
   const reduction = source > 0 ? ((saved / source) * 100).toFixed(1) : "0.0";
   const lines = [
     "Entroly protected the last context assembly",
+    "Provider routing: OpenClaw-managed (Entroly is provider-independent)",
+    `Budget source: ${status.budget_source ?? "unknown"}`,
     `Strategy: ${status.assembly_strategy ?? "budgeted_context"}`,
     `Evidence pinned verbatim: ${status.evidence_pinned ?? 0} message(s)`,
     `Evidence pins blocked by firewall: ${status.evidence_pin_blocked ?? 0}`,
@@ -24,8 +295,10 @@ export function formatEntrolyStatus(status) {
     `Estimated reduction: ${reduction}% (${saved.toLocaleString()} tokens)`,
     `Changed: ${status.changed ? "yes" : "no"}`,
   ];
-  if (status.receipt_id) lines.push(`Receipt: ${status.receipt_id}`);
-  if (status.warnings?.length) lines.push(`Warnings: ${status.warnings.join(" | ")}`);
+  if (status.receipt_id) lines.push(`Receipt: ${boundedString(status.receipt_id, 160)}`);
+  if (status.warnings?.length) {
+    lines.push(`Warnings: ${status.warnings.map((warning) => safeDiagnostic(warning)).join(" | ")}`);
+  }
   return lines.join("\n");
 }
 
@@ -34,11 +307,12 @@ export function formatEntrolyDoctor({ ok, error, pythonCommand = "python" }) {
     return [
       "Entroly doctor: ready",
       `Python command: ${pythonCommand}`,
-      "Bridge: responsive",
+      "Bridge: compatible (v2, two-phase receipts)",
       "Local-only context assembly: available",
+      "Provider-neutral bridge: ready; routing and authentication remain OpenClaw-managed",
     ].join("\n");
   }
-  const reason = String(error?.message ?? error ?? "unknown error").replace(/\s+/g, " ");
+  const reason = safeDiagnostic(error);
   return [
     "Entroly doctor: not ready",
     `Python command: ${pythonCommand}`,
@@ -50,16 +324,42 @@ export function formatEntrolyDoctor({ ok, error, pythonCommand = "python" }) {
 
 export function createEntrolyContextEngine({
   bridge,
+  delegateCompaction,
+  buildMemoryPrompt = () => undefined,
   config = {},
   logger = console,
   statusBySession = new Map(),
+  maxStatusSessions = 512,
 }) {
+  if (typeof delegateCompaction !== "function") {
+    throw new TypeError("Entroly requires OpenClaw's compaction delegate");
+  }
+  const statusLimit = positiveInteger(maxStatusSessions) ?? 512;
+  const storeStatus = (sessionId, status) => {
+    statusBySession.delete(sessionId);
+    statusBySession.set(sessionId, statusSnapshot(status));
+    while (statusBySession.size > statusLimit) {
+      statusBySession.delete(statusBySession.keys().next().value);
+    }
+  };
 
   return {
     info: {
       id: "entroly",
       name: "Entroly Context Engine",
       ownsCompaction: false,
+      hostRequirements: {
+        "agent-run": {
+          requiredCapabilities: ["assemble-before-prompt"],
+          unsupportedMessage:
+            "Entroly requires a native OpenClaw host that applies assembled context before each model call.",
+        },
+        "manual-compact": {
+          requiredCapabilities: ["compact"],
+          unsupportedMessage:
+            "Entroly delegates transcript compaction to the native OpenClaw runtime.",
+        },
+      },
     },
 
     async ingest() {
@@ -72,61 +372,150 @@ export function createEntrolyContextEngine({
 
     async assemble({
       sessionId,
+      sessionKey,
       messages,
       tokenBudget,
+      availableTools,
+      citationsMode,
       model,
       prompt,
       runtimeSettings,
     }) {
-      const sourceMessages = Array.isArray(messages) ? messages : [];
-      const effectiveBudget =
-        tokenBudget ?? runtimeSettings?.limits?.promptTokenBudget ?? DEFAULT_TOKEN_BUDGET;
+      if (!Array.isArray(messages)) {
+        const error = new TypeError(
+          "OpenClaw did not supply context messages as an array; Entroly refused to assemble an empty prompt",
+        );
+        logger.error?.(`entroly: ${safeDiagnostic(error)}`);
+        storeStatus(sessionId, { ok: false, error: error.message });
+        throw error;
+      }
+      const sourceMessages = messages;
+      const assemblyRuntime = resolveAssemblyRuntime({
+        tokenBudget,
+        model,
+        runtimeSettings,
+        fallbackTokenBudget: config.fallbackTokenBudget,
+      });
+      const preserveLastN = positiveInteger(config.preserveLastN) ?? 4;
+      let systemPromptAddition;
       try {
-        const result = await bridge.request({
-          operation: "assemble",
-          session_id: sessionId,
-          messages: sourceMessages,
-          token_budget: effectiveBudget,
-          model,
-          prompt,
-          workspace_dir: config.workspaceDir,
-          preserve_last_n: config.preserveLastN ?? 4,
-          receipt_dir: config.receiptDir,
-          write_receipt: config.writeReceipts !== false,
-          distill: config.distill !== false,
-          evidence_pinning: config.evidencePinning !== false,
+        systemPromptAddition = buildMemoryPrompt({
+          availableTools: availableTools ?? new Set(),
+          citationsMode,
+          agentSessionKey: sessionKey,
         });
-        statusBySession.set(sessionId, result);
-        return {
-          messages: result.messages,
-          estimatedTokens: result.estimated_tokens,
-          promptAuthority: "assembled",
-        };
       } catch (error) {
         logger.warn?.(
-          `entroly: assembly failed; passing exact original context: ${error.message}`,
+          `entroly: OpenClaw memory guidance could not be added: ${safeDiagnostic(error)}`,
         );
-        statusBySession.set(sessionId, {
+      }
+      const failOpen = (error) => {
+        const reason = safeDiagnostic(error);
+        logger.warn?.(`entroly: assembly failed; passing exact original context: ${reason}`);
+        storeStatus(sessionId, {
           ok: false,
-          error: error.message,
+          error: reason,
           estimated_tokens: estimateTokens(sourceMessages),
+          provider_mode: PROVIDER_MODE,
+          provider_independent: true,
+          budget_source: assemblyRuntime.budgetSource,
         });
         return {
           messages: sourceMessages,
           estimatedTokens: estimateTokens(sourceMessages),
           promptAuthority: "preassembly_may_overflow",
+          systemPromptAddition,
         };
+      };
+      if (assemblyRuntime.tokenBudget === undefined) {
+        return failOpen(
+          new Error(
+            "OpenClaw did not provide a positive prompt token budget; configure the model context window or plugins.entries.entroly.config.fallbackTokenBudget",
+          ),
+        );
+      }
+      try {
+        const receiptCommitToken =
+          config.writeReceipts === false ? null : randomBytes(32).toString("hex");
+        const result = validateAssemblyResult(
+          await bridge.request({
+            operation: "assemble",
+            session_id: sessionId,
+            messages: sourceMessages,
+            token_budget: assemblyRuntime.tokenBudget,
+            budget_source: assemblyRuntime.budgetSource,
+            model: assemblyRuntime.model,
+            openclaw_runtime: assemblyRuntime.runtimeMetadata,
+            prompt,
+            workspace_dir: config.workspaceDir,
+            preserve_last_n: preserveLastN,
+            receipt_dir: config.receiptDir,
+            write_receipt: config.writeReceipts !== false,
+            receipt_commit_challenge_sha256:
+              receiptCommitToken === null ? undefined : sha256(receiptCommitToken),
+            receipt_max_files: positiveInteger(config.receiptMaxFiles),
+            receipt_max_bytes: positiveInteger(config.receiptMaxBytes),
+            distill: config.distill !== false,
+            evidence_pinning: config.evidencePinning !== false,
+          }),
+          sourceMessages,
+          preserveLastN,
+        );
+        if (result.receipt_commit_required === true) {
+          const proposal = {
+            receiptId: boundedString(result.receipt_id, 160),
+            proposalId: boundedString(result.proposal_id, 160),
+            proposalSha256: boundedString(result.proposal_sha256, 64),
+            receiptPath: boundedString(result.receipt_path, 1024),
+            acceptanceCommitSha256:
+              receiptCommitToken === null
+                ? null
+                : sha256(
+                    `entroly.openclaw.accept.v1:${result.proposal_sha256}:${receiptCommitToken}`,
+                  ),
+          };
+          if (
+            !/^ocr_[0-9a-f]{20}$/.test(proposal.receiptId ?? "") ||
+            !/^ocp_[0-9a-f]{32}$/.test(proposal.proposalId ?? "") ||
+            !/^[0-9a-f]{64}$/.test(proposal.proposalSha256 ?? "") ||
+            !proposal.receiptPath
+          ) {
+            throw new Error("Entroly bridge returned an invalid receipt proposal");
+          }
+          validateReceiptCommit(
+            await bridge.request({
+              operation: "commit_receipt",
+              receipt_id: proposal.receiptId,
+              proposal_id: proposal.proposalId,
+              proposal_sha256: proposal.proposalSha256,
+              receipt_path: proposal.receiptPath,
+              receipt_commit_token: receiptCommitToken,
+              workspace_dir: config.workspaceDir,
+            }),
+            proposal,
+          );
+        } else if (result.receipt_path) {
+          throw new Error(
+            "Entroly bridge wrote a receipt without the required acceptance handshake",
+          );
+        }
+        storeStatus(sessionId, result);
+        return {
+          messages: result.messages,
+          estimatedTokens: result.estimated_tokens,
+          promptAuthority:
+            result.estimated_tokens > assemblyRuntime.tokenBudget
+              ? "preassembly_may_overflow"
+              : "assembled",
+          systemPromptAddition,
+        };
+      } catch (error) {
+        return failOpen(error);
       }
     },
 
-    async compact({ currentTokenCount }) {
-      return {
-        ok: true,
-        compacted: false,
-        reason:
-          "Entroly applies reversible per-turn context assembly and does not rewrite the OpenClaw transcript.",
-        result: { tokensBefore: currentTokenCount ?? 0 },
-      };
+    async compact(params) {
+      return await delegateCompaction(params);
     },
 
     getStatus(sessionId) {

package/index.js

@@ -1,4 +1,8 @@
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import {
+  buildMemorySystemPromptAddition,
+  delegateCompactionToRuntime,
+} from "openclaw/plugin-sdk/core";
 import { EntrolyBridgeClient } from "./bridge-client.js";
 import {
   createEntrolyContextEngine,
@@ -11,20 +15,24 @@ export default definePluginEntry({
   name: "Entroly Context Engine",
   register(api) {
     const config = api.pluginConfig ?? {};
+    let latestWorkspaceDir;
     const bridge = new EntrolyBridgeClient({
       pythonCommand: config.pythonCommand ?? "python",
       timeoutMs: config.timeoutMs ?? 5000,
       logger: api.logger,
     });
     const statusBySession = new Map();
-    api.registerContextEngine("entroly", (factoryContext) =>
-      createEntrolyContextEngine({
+    api.registerContextEngine("entroly", (factoryContext) => {
+      latestWorkspaceDir = factoryContext.workspaceDir;
+      return createEntrolyContextEngine({
         bridge,
+        delegateCompaction: delegateCompactionToRuntime,
+        buildMemoryPrompt: buildMemorySystemPromptAddition,
         config: { ...config, workspaceDir: factoryContext.workspaceDir },
         logger: api.logger,
         statusBySession,
-      }),
-    );
+      });
+    });
     api.registerCommand({
       name: "entroly-context",
       description: "Show Entroly context savings or run `doctor`.",
@@ -32,7 +40,11 @@ export default definePluginEntry({
       handler: async (ctx) => {
         if (ctx.args?.trim().toLowerCase() === "doctor") {
           try {
-            await bridge.health();
+            await bridge.health({
+              workspaceDir: latestWorkspaceDir,
+              receiptDir: config.receiptDir,
+              writeReceipts: config.writeReceipts !== false,
+            });
             return {
               text: formatEntrolyDoctor({
                 ok: true,

package/openclaw.plugin.json

@@ -4,7 +4,8 @@
     "onStartup": true
   },
   "name": "Entroly Context Engine",
-  "description": "Selects and compresses context under budget while preserving protected messages and writing local audit receipts.",
+  "description": "Provider-independent context assembly 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",
     "additionalProperties": false,
@@ -26,10 +27,27 @@
         "maximum": 30000,
         "default": 5000
       },
+      "fallbackTokenBudget": {
+        "type": "integer",
+        "minimum": 1024,
+        "maximum": 4000000
+      },
       "receiptDir": {
         "type": "string",
         "minLength": 1
       },
+      "receiptMaxFiles": {
+        "type": "integer",
+        "minimum": 8,
+        "maximum": 10000,
+        "default": 512
+      },
+      "receiptMaxBytes": {
+        "type": "integer",
+        "minimum": 1048576,
+        "maximum": 1073741824,
+        "default": 67108864
+      },
       "writeReceipts": {
         "type": "boolean",
         "default": true
@@ -57,10 +75,22 @@
       "label": "Bridge Timeout (ms)",
       "help": "Maximum time for one Entroly context assembly request."
     },
+    "fallbackTokenBudget": {
+      "label": "Fallback Prompt Token Budget",
+      "help": "Optional operator-approved budget used only when OpenClaw cannot resolve a finite model prompt budget."
+    },
     "receiptDir": {
       "label": "Receipt Directory",
       "help": "Optional local directory for Entroly OpenClaw receipts."
     },
+    "receiptMaxFiles": {
+      "label": "Receipt File Limit",
+      "help": "Fail safely instead of writing when this append-only receipt count is reached."
+    },
+    "receiptMaxBytes": {
+      "label": "Receipt Byte Limit",
+      "help": "Fail safely instead of allowing the receipt directory to exceed this byte quota."
+    },
     "writeReceipts": {
       "label": "Write Local Receipts",
       "help": "Record context hashes, estimated savings, warnings, and decision metadata locally."

package/package.json

@@ -1,9 +1,18 @@
 {
   "name": "entroly-openclaw",
-  "version": "1.0.53",
-  "description": "Auditable, budget-aware Entroly context engine for OpenClaw",
+  "version": "1.0.57",
+  "description": "Provider-independent, auditable context optimization for every OpenClaw model route",
   "type": "module",
   "license": "Apache-2.0",
+  "homepage": "https://github.com/juyterman1000/entroly#entroly-for-openclaw",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juyterman1000/entroly.git",
+    "directory": "integrations/openclaw"
+  },
+  "bugs": {
+    "url": "https://github.com/juyterman1000/entroly/issues"
+  },
   "engines": {
     "node": ">=22.19"
   },
@@ -32,12 +41,17 @@
       "./index.js"
     ],
     "install": {
+      "clawhubSpec": "clawhub:entroly-openclaw",
       "npmSpec": "entroly-openclaw",
       "defaultChoice": "npm",
       "minHostVersion": ">=2026.6.11"
     },
     "compat": {
-      "pluginApi": ">=2026.6.11"
+      "pluginApi": ">=2026.6.11",
+      "minGatewayVersion": ">=2026.6.11"
+    },
+    "build": {
+      "openclawVersion": "2026.6.11"
     },
     "release": {
       "publishToClawHub": true,