@martian-engineering/lossless-claw 0.9.4 → 0.10.0

package/doctor-contract-api.js

@@ -0,0 +1,231 @@
+const PLUGIN_ID = "lossless-claw";
+const ENTRY_PATH = ["plugins", "entries", PLUGIN_ID];
+const CONFIG_PATH = [...ENTRY_PATH, "config"];
+
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function readString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : "";
+}
+
+function readEntry(cfg) {
+  const plugins = isRecord(cfg) ? cfg.plugins : undefined;
+  const entries = isRecord(plugins) ? plugins.entries : undefined;
+  const entry = isRecord(entries) ? entries[PLUGIN_ID] : undefined;
+  return isRecord(entry) ? entry : undefined;
+}
+
+function readConfig(cfg) {
+  const config = readEntry(cfg)?.config;
+  return isRecord(config) ? config : undefined;
+}
+
+function readLlmPolicy(cfg) {
+  const llm = readEntry(cfg)?.llm;
+  if (!isRecord(llm)) {
+    return {
+      allowModelOverride: false,
+      allowedModels: [],
+    };
+  }
+  return {
+    allowModelOverride: llm.allowModelOverride === true,
+    allowedModels: Array.isArray(llm.allowedModels) ? llm.allowedModels : [],
+  };
+}
+
+function toModelRef(provider, model) {
+  const modelId = readString(model);
+  if (!modelId) {
+    return undefined;
+  }
+  const slash = modelId.indexOf("/");
+  if (slash > 0 && slash < modelId.length - 1) {
+    const directProvider = modelId.slice(0, slash).trim();
+    const directModel = modelId.slice(slash + 1).trim();
+    return directProvider && directModel ? `${directProvider}/${directModel}` : undefined;
+  }
+  const providerId = readString(provider);
+  return providerId ? `${providerId}/${modelId}` : undefined;
+}
+
+/** Collect configured Lossless summary model refs that doctor can safely allowlist. */
+function collectLosslessRuntimeLlmModelRefs(cfg) {
+  const config = readConfig(cfg);
+  if (!config) {
+    return { modelRefs: [], skipped: [] };
+  }
+
+  const modelRefs = [];
+  const skipped = [];
+  const addConfiguredModel = (field, model, provider, configPath) => {
+    const modelId = readString(model);
+    if (!modelId) {
+      return;
+    }
+    const modelRef = toModelRef(provider, modelId);
+    if (modelRef) {
+      modelRefs.push({ field, modelRef, configPath });
+      return;
+    }
+    skipped.push({
+      field,
+      configPath,
+      reason: `${field} is a bare model without a provider; use provider/model or set the matching provider field so doctor can update plugins.entries.${PLUGIN_ID}.llm.allowedModels.`,
+    });
+  };
+
+  addConfiguredModel(
+    "summaryModel",
+    config.summaryModel,
+    config.summaryProvider,
+    [...CONFIG_PATH, "summaryModel"].join("."),
+  );
+  addConfiguredModel(
+    "largeFileSummaryModel",
+    config.largeFileSummaryModel,
+    config.largeFileSummaryProvider,
+    [...CONFIG_PATH, "largeFileSummaryModel"].join("."),
+  );
+
+  if (Array.isArray(config.fallbackProviders)) {
+    for (const [index, fallback] of config.fallbackProviders.entries()) {
+      if (!isRecord(fallback)) {
+        skipped.push({
+          field: "fallbackProviders",
+          configPath: `${[...CONFIG_PATH, "fallbackProviders"].join(".")}[${index}]`,
+          reason:
+            "fallbackProviders entries must be objects with provider and model before doctor can update llm.allowedModels.",
+        });
+        continue;
+      }
+      const modelRef = toModelRef(fallback.provider, fallback.model);
+      if (modelRef) {
+        modelRefs.push({
+          field: "fallbackProviders",
+          modelRef,
+          configPath: `${[...CONFIG_PATH, "fallbackProviders"].join(".")}[${index}]`,
+        });
+      } else if (readString(fallback.model) || readString(fallback.provider)) {
+        skipped.push({
+          field: "fallbackProviders",
+          configPath: `${[...CONFIG_PATH, "fallbackProviders"].join(".")}[${index}]`,
+          reason:
+            "fallbackProviders entries need both provider and model before doctor can update llm.allowedModels.",
+        });
+      }
+    }
+  }
+
+  const seen = new Set();
+  return {
+    modelRefs: modelRefs.filter((entry) => {
+      const key = `${entry.field}:${entry.modelRef}`;
+      if (seen.has(key)) {
+        return false;
+      }
+      seen.add(key);
+      return true;
+    }),
+    skipped,
+  };
+}
+
+function collectMissingPolicyEntries(cfg) {
+  const { modelRefs, skipped } = collectLosslessRuntimeLlmModelRefs(cfg);
+  const policy = readLlmPolicy(cfg);
+  const allowedStrings = new Set(policy.allowedModels.filter((entry) => typeof entry === "string"));
+  const missingRefs = modelRefs.filter((entry) => !allowedStrings.has(entry.modelRef));
+  return {
+    modelRefs,
+    skipped,
+    missingRefs,
+    missingAllowModelOverride: modelRefs.length > 0 && policy.allowModelOverride !== true,
+  };
+}
+
+function hasIssueForField(cfg, field) {
+  const issues = collectMissingPolicyEntries(cfg);
+  return (
+    issues.missingAllowModelOverride ||
+    issues.missingRefs.some((entry) => entry.field === field) ||
+    issues.skipped.some((entry) => entry.field === field)
+  );
+}
+
+/** Doctor warning rules for Lossless runtime LLM model override policy. */
+export const legacyConfigRules = [
+  {
+    path: [...CONFIG_PATH, "summaryModel"],
+    message:
+      'Lossless summaryModel uses api.runtime.llm.complete model overrides. Configure plugins.entries.lossless-claw.llm.allowModelOverride and allowedModels, or run "openclaw doctor --fix".',
+    match: (_value, root) => hasIssueForField(root, "summaryModel"),
+  },
+  {
+    path: [...CONFIG_PATH, "largeFileSummaryModel"],
+    message:
+      'Lossless largeFileSummaryModel uses api.runtime.llm.complete model overrides. Configure plugins.entries.lossless-claw.llm.allowModelOverride and allowedModels, or run "openclaw doctor --fix".',
+    match: (_value, root) => hasIssueForField(root, "largeFileSummaryModel"),
+  },
+  {
+    path: [...CONFIG_PATH, "fallbackProviders"],
+    message:
+      'Lossless fallbackProviders use api.runtime.llm.complete model overrides. Configure plugins.entries.lossless-claw.llm.allowModelOverride and allowedModels, or run "openclaw doctor --fix".',
+    match: (_value, root) => hasIssueForField(root, "fallbackProviders"),
+  },
+];
+
+function cloneRootWithLosslessLlm(cfg) {
+  const root = isRecord(cfg) ? { ...cfg } : {};
+  const plugins = isRecord(root.plugins) ? { ...root.plugins } : {};
+  const entries = isRecord(plugins.entries) ? { ...plugins.entries } : {};
+  const entry = isRecord(entries[PLUGIN_ID]) ? { ...entries[PLUGIN_ID] } : {};
+  const llm = isRecord(entry.llm) ? { ...entry.llm } : {};
+
+  root.plugins = plugins;
+  plugins.entries = entries;
+  entries[PLUGIN_ID] = entry;
+  entry.llm = llm;
+
+  return { root, llm };
+}
+
+/** Add the minimal plugin runtime LLM policy needed for configured Lossless summary models. */
+export function normalizeCompatibilityConfig({ cfg }) {
+  const issues = collectMissingPolicyEntries(cfg);
+  if (issues.modelRefs.length === 0) {
+    return { config: cfg, changes: [] };
+  }
+
+  const { root, llm } = cloneRootWithLosslessLlm(cfg);
+  const changes = [];
+
+  if (llm.allowModelOverride !== true) {
+    llm.allowModelOverride = true;
+    changes.push("Set plugins.entries.lossless-claw.llm.allowModelOverride = true for configured Lossless summary model overrides.");
+  }
+
+  const currentAllowed = Array.isArray(llm.allowedModels) ? [...llm.allowedModels] : [];
+  const allowedStrings = new Set(currentAllowed.filter((entry) => typeof entry === "string"));
+  const added = [];
+  for (const { modelRef } of issues.modelRefs) {
+    if (!allowedStrings.has(modelRef)) {
+      currentAllowed.push(modelRef);
+      allowedStrings.add(modelRef);
+      added.push(modelRef);
+    }
+  }
+
+  if (added.length > 0 || !Array.isArray(llm.allowedModels)) {
+    llm.allowedModels = currentAllowed;
+    changes.push(
+      `Added plugins.entries.lossless-claw.llm.allowedModels entries for configured Lossless summary models: ${added.join(", ")}`,
+    );
+  }
+
+  return { config: root, changes };
+}
+
+export { collectLosslessRuntimeLlmModelRefs };

package/openclaw.plugin.json

@@ -24,9 +24,13 @@
       "label": "Context Threshold",
       "help": "Fraction of context window that triggers compaction (0.0–1.0)"
     },
+    "sweepMaxDepth": {
+      "label": "Sweep Max Depth",
+      "help": "Preferred maximum condensation source depth during routine full sweeps (0 = leaf only, -1 = unlimited). Pressure sweeps may go deeper when summarized context remains above target."
+    },
     "incrementalMaxDepth": {
-      "label": "Incremental Max Depth",
-      "help": "How deep incremental compaction goes (0 = leaf only, -1 = unlimited)"
+      "label": "Incremental Max Depth (Deprecated)",
+      "help": "Deprecated alias for sweepMaxDepth. Kept for existing configs."
     },
     "freshTailCount": {
       "label": "Fresh Tail Count",
@@ -40,9 +44,17 @@
       "label": "Prompt-Aware Eviction",
       "help": "When enabled, budget-constrained assembly keeps older context by prompt relevance instead of pure chronology. This can improve recall under tight budgets, but it can also reduce provider prompt-cache hit rates because the preserved prefix changes as prompts change."
     },
+    "stubLargeToolPayloads": {
+      "label": "Stub Large Tool Payloads",
+      "help": "When enabled, evictable tool-result rows whose payload was externalized via lcm-blob-migrate are replaced with a [LCM Tool Output: file_xxx | …] reference at assemble time. Fresh tail is never stubbed. The agent recovers the original output via lcm_describe(id=file_xxx, expandFile=true). Default off; requires running scripts/lcm-blob-migrate.mjs first to populate messages.large_content."
+    },
     "leafChunkTokens": {
       "label": "Leaf Chunk Tokens",
-      "help": "Maximum source tokens per leaf compaction chunk before summarization"
+      "help": "Maximum source tokens per leaf compaction chunk before summarization (default 20000)"
+    },
+    "summaryPrefixTargetTokens": {
+      "label": "Summary Prefix Target Tokens",
+      "help": "Optional target for summarized-prefix tokens after a full sweep. When omitted, Lossless derives a pressure target from contextThreshold and leafChunkTokens."
     },
     "bootstrapMaxTokens": {
       "label": "Bootstrap Max Tokens",
@@ -114,7 +126,7 @@
     },
     "summaryModel": {
       "label": "Summary Model",
-      "help": "Model override for LCM summarization (e.g., 'gpt-5.4' to reuse the session provider, or 'openai-resp/gpt-5.4' for a full cross-provider ref)"
+      "help": "Runtime LLM model override for LCM summarization (e.g., 'gpt-5.4' with summaryProvider, or 'openai-resp/gpt-5.4'); explicit overrides require plugins.entries.lossless-claw.llm policy"
     },
     "summaryProvider": {
       "label": "Summary Provider",
@@ -122,7 +134,7 @@
     },
     "largeFileSummaryModel": {
       "label": "Large File Summary Model",
-      "help": "Model override for large-file summarization"
+      "help": "Runtime LLM model override for large-file summarization; explicit overrides require plugins.entries.lossless-claw.llm policy"
     },
     "largeFileSummaryProvider": {
       "label": "Large File Summary Provider",
@@ -165,40 +177,40 @@
       "help": "Cooldown before the summarization circuit breaker auto-resets"
     },
     "cacheAwareCompaction.enabled": {
-      "label": "Cache-Aware Compaction",
-      "help": "When enabled, hot prompt cache defers incremental compaction while cold cache allows bounded catch-up passes"
+      "label": "Cache-Aware Compaction (Deprecated)",
+      "help": "Deprecated compatibility setting. Automatic compaction is now threshold-only and does not use prompt-cache hot/cold state."
     },
     "cacheAwareCompaction.cacheTTLSeconds": {
-      "label": "Short Cache TTL (seconds)",
-      "help": "Treat short-lived prompt-cache entries as hot for this many seconds before deferred compaction may rewrite the prompt"
+      "label": "Short Cache TTL (Deprecated)",
+      "help": "Deprecated compatibility setting. Threshold debt no longer waits for cache TTL."
     },
     "cacheAwareCompaction.maxColdCacheCatchupPasses": {
-      "label": "Cold Cache Catch-Up Passes",
-      "help": "Maximum incremental leaf passes allowed in one maintenance cycle when prompt cache is cold"
+      "label": "Cold Cache Catch-Up (Deprecated)",
+      "help": "Deprecated compatibility setting. Automatic cold-cache catch-up passes were removed."
     },
     "cacheAwareCompaction.hotCachePressureFactor": {
-      "label": "Hot Cache Pressure Factor",
-      "help": "Multiplier applied to the hot-cache leaf trigger before raw-history pressure overrides cache preservation"
+      "label": "Hot Cache Pressure (Deprecated)",
+      "help": "Deprecated compatibility setting. Hot-cache raw-history pressure no longer drives automatic compaction."
     },
     "cacheAwareCompaction.hotCacheBudgetHeadroomRatio": {
-      "label": "Hot Cache Budget Headroom",
-      "help": "Fraction of the real token budget that must remain free before hot-cache incremental compaction is skipped entirely"
+      "label": "Hot Cache Headroom (Deprecated)",
+      "help": "Deprecated compatibility setting. Hot-cache budget headroom no longer defers threshold compaction."
     },
     "cacheAwareCompaction.coldCacheObservationThreshold": {
-      "label": "Cold Cache Observation Threshold",
-      "help": "Consecutive cold observations required before non-explicit cache misses are treated as truly cold"
+      "label": "Cold Cache Observations (Deprecated)",
+      "help": "Deprecated compatibility setting. Cold-cache streaks are diagnostic only."
     },
     "cacheAwareCompaction.criticalBudgetPressureRatio": {
-      "label": "Critical Budget Pressure Ratio",
-      "help": "Fraction of token budget at which deferred compaction fires regardless of prompt-cache state. Defaults to 0.70 — set to 1 to disable the override and let cache-aware throttling fully control deferral."
+      "label": "Critical Budget Pressure (Deprecated)",
+      "help": "Deprecated compatibility setting. contextThreshold is now the only automatic compaction threshold."
     },
     "dynamicLeafChunkTokens.enabled": {
-      "label": "Dynamic Leaf Chunk Tokens",
-      "help": "When enabled, incremental compaction uses a larger working leaf chunk in busy sessions and keeps the static floor in quieter sessions"
+      "label": "Dynamic Leaf Chunks (Deprecated)",
+      "help": "Deprecated compatibility setting. Automatic compaction now uses leafChunkTokens directly."
     },
     "dynamicLeafChunkTokens.max": {
-      "label": "Dynamic Leaf Chunk Max",
-      "help": "Maximum working leaf chunk target for dynamic incremental compaction. The static leafChunkTokens value remains the floor."
+      "label": "Dynamic Leaf Chunk Max (Deprecated)",
+      "help": "Deprecated compatibility setting. Automatic compaction now uses leafChunkTokens directly."
     },
     "timezone": {
       "label": "Timezone",
@@ -220,6 +232,10 @@
       "label": "Auto-Rotate Session Files",
       "help": "Automatically rotate oversized LCM-managed session JSONL files after startup and runtime checks"
     },
+    "autoRotateSessionFiles.createBackups": {
+      "label": "Auto-Rotate Backups",
+      "help": "Create the rolling rotate-latest SQLite backup before automatic session-file rotation; disabled by default"
+    },
     "autoRotateSessionFiles.sizeBytes": {
       "label": "Auto-Rotate Size Bytes",
       "help": "Session JSONL byte threshold for automatic rotation (default: 2097152)"
@@ -234,7 +250,7 @@
     },
     "fallbackProviders": {
       "label": "Fallback Providers",
-      "help": "Explicit fallback provider/model pairs for compaction summarization (e.g., [{\"provider\": \"anthropic\", \"model\": \"claude-haiku-4-5\"}])"
+      "help": "Explicit runtime LLM fallback provider/model pairs for compaction summarization; entries require plugins.entries.lossless-claw.llm policy"
     }
   },
   "configSchema": {
@@ -249,6 +265,10 @@
         "minimum": 0,
         "maximum": 1
       },
+      "sweepMaxDepth": {
+        "type": "integer",
+        "minimum": -1
+      },
       "incrementalMaxDepth": {
         "type": "integer",
         "minimum": -1
@@ -264,10 +284,17 @@
       "promptAwareEviction": {
         "type": "boolean"
       },
+      "stubLargeToolPayloads": {
+        "type": "boolean"
+      },
       "leafChunkTokens": {
         "type": "integer",
         "minimum": 1
       },
+      "summaryPrefixTargetTokens": {
+        "type": "integer",
+        "minimum": 1
+      },
       "bootstrapMaxTokens": {
         "type": "integer",
         "minimum": 1
@@ -445,6 +472,9 @@
           "enabled": {
             "type": "boolean"
           },
+          "createBackups": {
+            "type": "boolean"
+          },
           "sizeBytes": {
             "type": "integer",
             "minimum": 1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@martian-engineering/lossless-claw",
-  "version": "0.9.4",
-  "description": "Lossless Context Management plugin for OpenClaw — DAG-based conversation summarization with incremental compaction",
+  "version": "0.10.0",
+  "description": "Lossless Context Management plugin for OpenClaw — DAG-based conversation summarization with threshold compaction",
   "type": "module",
   "main": "dist/index.js",
   "license": "MIT",
@@ -16,7 +16,7 @@
     "dag"
   ],
   "scripts": {
-    "build": "esbuild index.ts --bundle --platform=node --target=node22 --format=esm --outfile=dist/index.js --external:openclaw --external:\"@mariozechner/*\" --minify-whitespace",
+    "build": "esbuild index.ts --bundle --platform=node --target=node22 --format=esm --outfile=dist/index.js --external:openclaw --external:\"@earendil-works/*\" --minify-whitespace",
     "changeset": "changeset",
     "release:verify": "npm run build && npm test && npm pack --dry-run",
     "test": "vitest run --dir test",
@@ -24,6 +24,8 @@
   },
   "files": [
     "dist/",
+    "doctor-contract-api.d.ts",
+    "doctor-contract-api.js",
     "skills/",
     "openclaw.plugin.json",
     "docs/",
@@ -31,35 +33,21 @@
     "LICENSE"
   ],
   "dependencies": {
+    "@earendil-works/pi-agent-core": ">=0.74 <1",
+    "@earendil-works/pi-ai": ">=0.74 <1",
+    "@earendil-works/pi-coding-agent": ">=0.74 <1",
     "@sinclair/typebox": "0.34.48"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.6.0",
     "@changesets/cli": "^2.30.0",
-    "@mariozechner/pi-agent-core": "0.66.1",
-    "@mariozechner/pi-ai": "0.66.1",
-    "@mariozechner/pi-coding-agent": "0.66.1",
     "esbuild": "^0.28.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   },
   "peerDependencies": {
-    "@mariozechner/pi-agent-core": ">=0.66 <1",
-    "@mariozechner/pi-ai": ">=0.66 <1",
-    "@mariozechner/pi-coding-agent": ">=0.66 <1",
     "openclaw": ">=2026.2.17 <2026.6.0"
   },
-  "peerDependenciesMeta": {
-    "@mariozechner/pi-agent-core": {
-      "optional": true
-    },
-    "@mariozechner/pi-ai": {
-      "optional": true
-    },
-    "@mariozechner/pi-coding-agent": {
-      "optional": true
-    }
-  },
   "publishConfig": {
     "access": "public"
   },