entroly-openclaw 1.0.46

package/README.md

@@ -0,0 +1,78 @@
+# Entroly for OpenClaw
+
+Entroly provides budget-aware, auditable context assembly for OpenClaw while
+leaving OpenClaw's persisted transcript untouched.
+
+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.
+
+## Install
+
+After the package is published:
+
+```bash
+pip install entroly
+openclaw plugins install entroly-openclaw
+openclaw plugins enable entroly
+```
+
+From an Entroly source checkout:
+
+```bash
+pip install entroly
+openclaw plugins install ./integrations/openclaw
+openclaw plugins enable entroly
+```
+
+Select the engine in `~/.openclaw/openclaw.json`:
+
+```json5
+{
+  plugins: {
+    slots: {
+      contextEngine: "entroly"
+    }
+  }
+}
+```
+
+Restart the Gateway and verify the loaded plugin with:
+
+```bash
+openclaw plugins inspect entroly --runtime --json
+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.
+
+## Reproduce the evidence-pinning control
+
+```bash
+python -m benchmarks.openclaw_evidence_pinning
+```
+
+The committed synthetic workload compares query-aware evidence pinning with
+uniform budget compression at the same estimated token budget. See the
+[result JSON](../../benchmarks/results/openclaw_evidence_pinning.json). It uses
+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.
+Entroly makes no remote calls in this path.
+
+## Safety contract
+
+- System and developer messages are never modified.
+- Structured message content is never modified.
+- Recent messages are preserved verbatim.
+- Bridge errors return the exact original message list.
+- Entroly does not rewrite the OpenClaw transcript or claim persistent
+  compaction.

package/bridge-client.js

@@ -0,0 +1,119 @@
+import { spawn } from "node:child_process";
+import readline from "node:readline";
+
+export class EntrolyBridgeClient {
+  constructor({
+    pythonCommand = "python",
+    timeoutMs = 5000,
+    logger = console,
+    spawnProcess = spawn,
+  } = {}) {
+    this.pythonCommand = pythonCommand;
+    this.timeoutMs = timeoutMs;
+    this.logger = logger;
+    this.spawnProcess = spawnProcess;
+    this.nextId = 1;
+    this.pending = new Map();
+    this.process = undefined;
+  }
+
+  start() {
+    if (this.process && !this.process.killed) {
+      return this.process;
+    }
+    const child = this.spawnProcess(
+      this.pythonCommand,
+      ["-m", "entroly.openclaw_bridge", "--jsonl"],
+      { stdio: ["pipe", "pipe", "pipe"], windowsHide: true },
+    );
+    this.process = child;
+    const lines = readline.createInterface({ input: child.stdout });
+    lines.on("line", (line) => this.#onLine(line));
+    child.stderr.on("data", (chunk) => {
+      const message = String(chunk).trim();
+      if (message) this.logger.warn?.(`entroly bridge: ${message}`);
+    });
+    child.on("error", (error) => this.#handleChildFailure(child, error));
+    child.on("exit", (code, signal) => {
+      this.#handleChildFailure(
+        child,
+        new Error(`Entroly bridge exited (${code ?? signal ?? "unknown"})`),
+      );
+    });
+    return child;
+  }
+
+  request(payload) {
+    const child = this.start();
+    const requestId = String(this.nextId++);
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#terminate(
+          child,
+          new Error(`Entroly bridge timed out after ${this.timeoutMs}ms`),
+        );
+      }, this.timeoutMs);
+      this.pending.set(requestId, { resolve, reject, timer });
+      child.stdin.write(`${JSON.stringify({ ...payload, request_id: requestId })}\n`, (error) => {
+        if (!error) return;
+        this.#terminate(child, error);
+      });
+    });
+  }
+
+  health() {
+    return this.request({ operation: "health" });
+  }
+
+  #onLine(line) {
+    let response;
+    try {
+      response = JSON.parse(line);
+    } catch (error) {
+      this.logger.warn?.(`entroly bridge emitted invalid JSON: ${error.message}`);
+      return;
+    }
+    const pending = this.pending.get(String(response.request_id));
+    if (!pending) return;
+    clearTimeout(pending.timer);
+    this.pending.delete(String(response.request_id));
+    if (response.ok) pending.resolve(response);
+    else pending.reject(new Error(response.error || "Entroly bridge request failed"));
+  }
+
+  #failAll(error) {
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(error);
+    }
+    this.pending.clear();
+  }
+
+  #handleChildFailure(child, error) {
+    if (this.process !== child) return;
+    this.process = undefined;
+    this.#failAll(error);
+  }
+
+  #terminate(child, error) {
+    if (this.process !== child) return;
+    this.process = undefined;
+    this.#failAll(error);
+    child.stdin.destroy();
+    if (!child.killed) child.kill();
+  }
+
+  async dispose() {
+    const child = this.process;
+    this.process = undefined;
+    if (!child || child.killed) return;
+    this.#failAll(new Error("Entroly bridge disposed"));
+    child.stdin.end();
+    // Brief grace for the process to exit on stdin EOF before SIGTERM.
+    await new Promise((resolve) => {
+      const timer = setTimeout(() => resolve(), 200);
+      child.on("exit", () => { clearTimeout(timer); resolve(); });
+    });
+    if (!child.killed) child.kill();
+  }
+}

package/engine.js

@@ -0,0 +1,140 @@
+const DEFAULT_TOKEN_BUDGET = 50_000;
+
+function estimateTokens(messages) {
+  return Math.ceil(JSON.stringify(messages).length / 4);
+}
+
+export function formatEntrolyStatus(status) {
+  if (!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}`;
+  }
+  const source = status.source_tokens ?? 0;
+  const assembled = status.estimated_tokens ?? source;
+  const saved = status.tokens_saved ?? Math.max(0, source - assembled);
+  const reduction = source > 0 ? ((saved / source) * 100).toFixed(1) : "0.0";
+  const lines = [
+    "Entroly protected the last context assembly",
+    `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}`,
+    `Estimated tokens: ${source.toLocaleString()} -> ${assembled.toLocaleString()}`,
+    `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(" | ")}`);
+  return lines.join("\n");
+}
+
+export function formatEntrolyDoctor({ ok, error, pythonCommand = "python" }) {
+  if (ok) {
+    return [
+      "Entroly doctor: ready",
+      `Python command: ${pythonCommand}`,
+      "Bridge: responsive",
+      "Local-only context assembly: available",
+    ].join("\n");
+  }
+  const reason = String(error?.message ?? error ?? "unknown error").replace(/\s+/g, " ");
+  return [
+    "Entroly doctor: not ready",
+    `Python command: ${pythonCommand}`,
+    `Reason: ${reason}`,
+    "Fix: install Entroly into that Python environment with `python -m pip install -U entroly`,",
+    "or set plugins.entries.entroly.config.pythonCommand to the correct Python executable.",
+  ].join("\n");
+}
+
+export function createEntrolyContextEngine({
+  bridge,
+  config = {},
+  logger = console,
+  statusBySession = new Map(),
+}) {
+
+  return {
+    info: {
+      id: "entroly",
+      name: "Entroly Context Engine",
+      ownsCompaction: false,
+    },
+
+    async ingest() {
+      return { ingested: false };
+    },
+
+    async ingestBatch() {
+      return { ingestedCount: 0 };
+    },
+
+    async assemble({
+      sessionId,
+      messages,
+      tokenBudget,
+      model,
+      prompt,
+      runtimeSettings,
+    }) {
+      const sourceMessages = Array.isArray(messages) ? messages : [];
+      const effectiveBudget =
+        tokenBudget ?? runtimeSettings?.limits?.promptTokenBudget ?? DEFAULT_TOKEN_BUDGET;
+      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,
+        });
+        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}`,
+        );
+        statusBySession.set(sessionId, {
+          ok: false,
+          error: error.message,
+          estimated_tokens: estimateTokens(sourceMessages),
+        });
+        return {
+          messages: sourceMessages,
+          estimatedTokens: estimateTokens(sourceMessages),
+          promptAuthority: "preassembly_may_overflow",
+        };
+      }
+    },
+
+    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 },
+      };
+    },
+
+    getStatus(sessionId) {
+      return statusBySession.get(sessionId);
+    },
+
+    async dispose() {
+      await bridge.dispose();
+    },
+  };
+}

package/index.js

@@ -0,0 +1,60 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { EntrolyBridgeClient } from "./bridge-client.js";
+import {
+  createEntrolyContextEngine,
+  formatEntrolyDoctor,
+  formatEntrolyStatus,
+} from "./engine.js";
+
+export default definePluginEntry({
+  id: "entroly",
+  name: "Entroly Context Engine",
+  register(api) {
+    const config = api.pluginConfig ?? {};
+    const bridge = new EntrolyBridgeClient({
+      pythonCommand: config.pythonCommand ?? "python",
+      timeoutMs: config.timeoutMs ?? 5000,
+      logger: api.logger,
+    });
+    const statusBySession = new Map();
+    api.registerContextEngine("entroly", (factoryContext) =>
+      createEntrolyContextEngine({
+        bridge,
+        config: { ...config, workspaceDir: factoryContext.workspaceDir },
+        logger: api.logger,
+        statusBySession,
+      }),
+    );
+    api.registerCommand({
+      name: "entroly-context",
+      description: "Show Entroly context savings or run `doctor`.",
+      acceptsArgs: true,
+      handler: async (ctx) => {
+        if (ctx.args?.trim().toLowerCase() === "doctor") {
+          try {
+            await bridge.health();
+            return {
+              text: formatEntrolyDoctor({
+                ok: true,
+                pythonCommand: config.pythonCommand ?? "python",
+              }),
+            };
+          } catch (error) {
+            return {
+              text: formatEntrolyDoctor({
+                ok: false,
+                error,
+                pythonCommand: config.pythonCommand ?? "python",
+              }),
+            };
+          }
+        }
+        return {
+          text: formatEntrolyStatus(
+            ctx.sessionId ? statusBySession.get(ctx.sessionId) : undefined,
+          ),
+        };
+      },
+    });
+  },
+});

package/openclaw.plugin.json

@@ -0,0 +1,77 @@
+{
+  "id": "entroly",
+  "activation": {
+    "onStartup": true
+  },
+  "name": "Entroly Context Engine",
+  "description": "Selects and compresses context under budget while preserving protected messages and writing local audit receipts.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "pythonCommand": {
+        "type": "string",
+        "minLength": 1,
+        "default": "python"
+      },
+      "preserveLastN": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 32,
+        "default": 4
+      },
+      "timeoutMs": {
+        "type": "integer",
+        "minimum": 100,
+        "maximum": 30000,
+        "default": 5000
+      },
+      "receiptDir": {
+        "type": "string",
+        "minLength": 1
+      },
+      "writeReceipts": {
+        "type": "boolean",
+        "default": true
+      },
+      "distill": {
+        "type": "boolean",
+        "default": true
+      },
+      "evidencePinning": {
+        "type": "boolean",
+        "default": true
+      }
+    }
+  },
+  "uiHints": {
+    "pythonCommand": {
+      "label": "Python Command",
+      "help": "Python executable where the entroly package is installed."
+    },
+    "preserveLastN": {
+      "label": "Recent Messages Preserved",
+      "help": "Number of recent messages kept byte-for-byte unchanged."
+    },
+    "timeoutMs": {
+      "label": "Bridge Timeout (ms)",
+      "help": "Maximum time for one Entroly context assembly request."
+    },
+    "receiptDir": {
+      "label": "Receipt Directory",
+      "help": "Optional local directory for Entroly OpenClaw receipts."
+    },
+    "writeReceipts": {
+      "label": "Write Local Receipts",
+      "help": "Record context hashes, estimated savings, warnings, and decision metadata locally."
+    },
+    "distill": {
+      "label": "Distill Older Assistant Messages",
+      "help": "Remove filler from compressible older assistant responses before budget compression."
+    },
+    "evidencePinning": {
+      "label": "Query-Aware Evidence Pinning",
+      "help": "Keep older messages that match the current request verbatim when they fit the bounded evidence reserve."
+    }
+  }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "entroly-openclaw",
+  "version": "1.0.46",
+  "description": "Auditable, budget-aware Entroly context engine for OpenClaw",
+  "type": "module",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22.19"
+  },
+  "files": [
+    "bridge-client.js",
+    "engine.js",
+    "index.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",
+    "pack:check": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.6.11"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.js"
+    ],
+    "install": {
+      "npmSpec": "entroly-openclaw",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.6.11"
+    },
+    "compat": {
+      "pluginApi": ">=2026.6.11"
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true,
+      "bundleRuntimeDependencies": false
+    }
+  }
+}