@martian-engineering/lossless-claw 0.1.0 → 0.1.2

package/README.md

@@ -26,12 +26,17 @@ Nothing is lost. Raw messages stay in the database. Summaries link back to their
 
 ### Install the plugin
 
+**From npm** (recommended):
+
+```bash
+npm install @martian-engineering/lossless-claw
+```
+
+**From source** (for development):
+
 ```bash
-# Clone the repo
 git clone https://github.com/Martian-Engineering/lossless-claw.git
 cd lossless-claw
-
-# Install dependencies
 npm install
 ```
 
@@ -39,6 +44,21 @@ npm install
 
 Add the plugin to your OpenClaw config (`~/.openclaw/openclaw.json`):
 
+```json
+{
+  "plugins": {
+    "paths": [
+      "node_modules/@martian-engineering/lossless-claw"
+    ],
+    "slots": {
+      "contextEngine": "lossless-claw"
+    }
+  }
+}
+```
+
+If installed from source, use the absolute path to the cloned repo instead:
+
 ```json
 {
   "plugins": {

package/docs/configuration.md

@@ -2,12 +2,16 @@
 
 ## Quick start
 
-Add LCM to your OpenClaw config:
+Install the plugin and add it to your OpenClaw config:
+
+```bash
+npm install @martian-engineering/lossless-claw
+```
 
 ```json
 {
   "plugins": {
-    "paths": ["/path/to/lossless-claw"],
+    "paths": ["node_modules/@martian-engineering/lossless-claw"],
     "slots": {
       "contextEngine": "lossless-claw"
     }
@@ -15,6 +19,8 @@ Add LCM to your OpenClaw config:
 }
 ```
 
+If installed from source, use the absolute path to the repo instead of `node_modules/...`.
+
 Set recommended environment variables:
 
 ```bash

package/index.ts

@@ -39,8 +39,29 @@ function normalizeAgentId(agentId: string | undefined): string {
   return normalized.length > 0 ? normalized : "main";
 }
 
+type PluginEnvSnapshot = {
+  lcmSummaryModel: string;
+  lcmSummaryProvider: string;
+  openclawProvider: string;
+  agentDir: string;
+  home: string;
+};
+
+type ReadEnvFn = (key: string) => string | undefined;
+
+/** Capture plugin env values once during initialization. */
+function snapshotPluginEnv(env: NodeJS.ProcessEnv = process.env): PluginEnvSnapshot {
+  return {
+    lcmSummaryModel: env.LCM_SUMMARY_MODEL?.trim() ?? "",
+    lcmSummaryProvider: env.LCM_SUMMARY_PROVIDER?.trim() ?? "",
+    openclawProvider: env.OPENCLAW_PROVIDER?.trim() ?? "",
+    agentDir: env.OPENCLAW_AGENT_DIR?.trim() || env.PI_CODING_AGENT_DIR?.trim() || "",
+    home: env.HOME?.trim() ?? "",
+  };
+}
+
 /** Resolve common provider API keys from environment. */
-function resolveApiKey(provider: string): string | undefined {
+function resolveApiKey(provider: string, readEnv: ReadEnvFn): string | undefined {
   const keyMap: Record<string, string[]> = {
     openai: ["OPENAI_API_KEY"],
     anthropic: ["ANTHROPIC_API_KEY"],
@@ -59,7 +80,7 @@ function resolveApiKey(provider: string): string | undefined {
   keys.push(normalizedProviderEnv);
 
   for (const key of keys) {
-    const value = process.env[key]?.trim();
+    const value = readEnv(key)?.trim();
     if (value) {
       return value;
     }
@@ -255,19 +276,19 @@ function mergeAuthProfileStores(stores: AuthProfileStore[]): AuthProfileStore |
 }
 
 /** Determine candidate auth store paths ordered by precedence. */
-function resolveAuthStorePaths(agentDir?: string): string[] {
+function resolveAuthStorePaths(params: { agentDir?: string; envSnapshot: PluginEnvSnapshot }): string[] {
   const paths: string[] = [];
-  const directAgentDir = agentDir?.trim();
+  const directAgentDir = params.agentDir?.trim();
   if (directAgentDir) {
     paths.push(join(directAgentDir, "auth-profiles.json"));
   }
 
-  const envAgentDir = process.env.OPENCLAW_AGENT_DIR?.trim() || process.env.PI_CODING_AGENT_DIR?.trim();
+  const envAgentDir = params.envSnapshot.agentDir;
   if (envAgentDir) {
     paths.push(join(envAgentDir, "auth-profiles.json"));
   }
 
-  const home = process.env.HOME?.trim();
+  const home = params.envSnapshot.home;
   if (home) {
     paths.push(join(home, ".openclaw", "agents", "main", "agent", "auth-profiles.json"));
   }
@@ -334,8 +355,12 @@ async function resolveApiKeyFromAuthProfiles(params: {
   agentDir?: string;
   runtimeConfig?: unknown;
   piAiModule: PiAiModule;
+  envSnapshot: PluginEnvSnapshot;
 }): Promise<string | undefined> {
-  const storesWithPaths = resolveAuthStorePaths(params.agentDir)
+  const storesWithPaths = resolveAuthStorePaths({
+    agentDir: params.agentDir,
+    envSnapshot: params.envSnapshot,
+  })
     .map((path) => {
       try {
         const parsed = parseAuthProfileStore(readFileSync(path, "utf8"));
@@ -526,7 +551,9 @@ function readLatestAssistantReply(messages: unknown[]): string | undefined {
 
 /** Construct LCM dependencies from plugin API/runtime surfaces. */
 function createLcmDependencies(api: OpenClawPluginApi): LcmDependencies {
-  const config = resolveLcmConfig(process.env);
+  const envSnapshot = snapshotPluginEnv();
+  const readEnv: ReadEnvFn = (key) => process.env[key];
+  const config = resolveLcmConfig();
 
   return {
     config,
@@ -602,7 +629,7 @@ function createLcmDependencies(api: OpenClawPluginApi): LcmDependencies {
                 maxTokens: 8_000,
               };
 
-        let resolvedApiKey = apiKey?.trim() || resolveApiKey(providerId);
+        let resolvedApiKey = apiKey?.trim() || resolveApiKey(providerId, readEnv);
         if (!resolvedApiKey && typeof mod.getEnvApiKey === "function") {
           resolvedApiKey = mod.getEnvApiKey(providerId)?.trim();
         }
@@ -613,6 +640,7 @@ function createLcmDependencies(api: OpenClawPluginApi): LcmDependencies {
             agentDir,
             runtimeConfig,
             piAiModule: mod,
+            envSnapshot,
           });
         }
 
@@ -673,7 +701,7 @@ function createLcmDependencies(api: OpenClawPluginApi): LcmDependencies {
       }
     },
     resolveModel: (modelRef, providerHint) => {
-      const raw = (modelRef ?? process.env.LCM_SUMMARY_MODEL ?? "").trim();
+      const raw = (modelRef ?? envSnapshot.lcmSummaryModel).trim();
       if (!raw) {
         throw new Error("No model configured for LCM summarization.");
       }
@@ -688,15 +716,15 @@ function createLcmDependencies(api: OpenClawPluginApi): LcmDependencies {
 
       const provider = (
         providerHint?.trim() ||
-        process.env.LCM_SUMMARY_PROVIDER ||
-        process.env.OPENCLAW_PROVIDER ||
+        envSnapshot.lcmSummaryProvider ||
+        envSnapshot.openclawProvider ||
         "openai"
       ).trim();
       return { provider, model: raw };
     },
-    getApiKey: (provider) => resolveApiKey(provider),
+    getApiKey: (provider) => resolveApiKey(provider, readEnv),
     requireApiKey: (provider) => {
-      const key = resolveApiKey(provider);
+      const key = resolveApiKey(provider, readEnv);
       if (!key) {
         throw new Error(`Missing API key for provider '${provider}'.`);
       }
@@ -756,7 +784,7 @@ const lcmPlugin = {
           ? (value as Record<string, unknown>)
           : {};
       const enabled = typeof raw.enabled === "boolean" ? raw.enabled : undefined;
-      const config = resolveLcmConfig(process.env);
+      const config = resolveLcmConfig();
       if (enabled !== undefined) {
         config.enabled = enabled;
       }

package/openclaw.plugin.json

@@ -0,0 +1,62 @@
+{
+  "id": "lossless-claw",
+  "uiHints": {
+    "contextThreshold": {
+      "label": "Context Threshold",
+      "help": "Fraction of context window that triggers compaction (0.0–1.0)"
+    },
+    "incrementalMaxDepth": {
+      "label": "Incremental Max Depth",
+      "help": "How deep incremental compaction goes (0 = leaf only)"
+    },
+    "freshTailCount": {
+      "label": "Fresh Tail Count",
+      "help": "Number of recent messages protected from compaction"
+    },
+    "dbPath": {
+      "label": "Database Path",
+      "help": "Path to LCM SQLite database (default: ~/.openclaw/lcm.db)"
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean"
+      },
+      "contextThreshold": {
+        "type": "number",
+        "minimum": 0,
+        "maximum": 1
+      },
+      "incrementalMaxDepth": {
+        "type": "integer",
+        "minimum": 0
+      },
+      "freshTailCount": {
+        "type": "integer",
+        "minimum": 1
+      },
+      "leafMinFanout": {
+        "type": "integer",
+        "minimum": 2
+      },
+      "condensedMinFanout": {
+        "type": "integer",
+        "minimum": 2
+      },
+      "condensedMinFanoutHard": {
+        "type": "integer",
+        "minimum": 2
+      },
+      "dbPath": {
+        "type": "string"
+      },
+      "largeFileThresholdTokens": {
+        "type": "integer",
+        "minimum": 1000
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martian-engineering/lossless-claw",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Lossless Context Management plugin for OpenClaw — DAG-based conversation summarization with incremental compaction",
   "type": "module",
   "main": "index.ts",
@@ -18,6 +18,7 @@
   "files": [
     "index.ts",
     "src/**/*.ts",
+    "openclaw.plugin.json",
     "docs/",
     "README.md",
     "LICENSE"

package/src/db/config.ts

@@ -15,6 +15,10 @@ export type LcmConfig = {
   condensedTargetTokens: number;
   maxExpandTokens: number;
   largeFileTokenThreshold: number;
+  /** Provider override for large-file text summarization. */
+  largeFileSummaryProvider: string;
+  /** Model override for large-file text summarization. */
+  largeFileSummaryModel: string;
   autocompactDisabled: boolean;
   /** IANA timezone for timestamps in summaries (from TZ env or system default) */
   timezone: string;
@@ -37,6 +41,8 @@ export function resolveLcmConfig(env: NodeJS.ProcessEnv = process.env): LcmConfi
     condensedTargetTokens: parseInt(env.LCM_CONDENSED_TARGET_TOKENS ?? "2000", 10),
     maxExpandTokens: parseInt(env.LCM_MAX_EXPAND_TOKENS ?? "4000", 10),
     largeFileTokenThreshold: parseInt(env.LCM_LARGE_FILE_TOKEN_THRESHOLD ?? "25000", 10),
+    largeFileSummaryProvider: env.LCM_LARGE_FILE_SUMMARY_PROVIDER?.trim() ?? "",
+    largeFileSummaryModel: env.LCM_LARGE_FILE_SUMMARY_MODEL?.trim() ?? "",
     autocompactDisabled: env.LCM_AUTOCOMPACT_DISABLED === "true",
     timezone: env.TZ ?? Intl.DateTimeFormat().resolvedOptions().timeZone,
     pruneHeartbeatOk: env.LCM_PRUNE_HEARTBEAT_OK === "true",

package/src/engine.ts

@@ -647,9 +647,7 @@ export class LcmContextEngine implements ContextEngine {
     customInstructions?: string;
   }): Promise<(text: string, aggressive?: boolean) => Promise<string>> {
     const lp = params.legacyParams ?? {};
-    console.error(`[lcm] resolveSummarize called, legacyParams keys: ${Object.keys(lp).join(",")}, has summarize fn: ${typeof lp.summarize === "function"}`);
     if (typeof lp.summarize === "function") {
-      console.error(`[lcm] resolveSummarize: using legacy summarize function`);
       return lp.summarize as (text: string, aggressive?: boolean) => Promise<string>;
     }
     try {
@@ -659,7 +657,6 @@ export class LcmContextEngine implements ContextEngine {
         customInstructions: params.customInstructions,
       });
       if (runtimeSummarizer) {
-        console.error(`[lcm] resolveSummarize: got runtime summarizer`);
         return runtimeSummarizer;
       }
       console.error(`[lcm] resolveSummarize: createLcmSummarizeFromLegacyParams returned undefined`);
@@ -684,8 +681,8 @@ export class LcmContextEngine implements ContextEngine {
     }
     this.largeFileTextSummarizerResolved = true;
 
-    const provider = process.env.LCM_LARGE_FILE_SUMMARY_PROVIDER?.trim() ?? "";
-    const model = process.env.LCM_LARGE_FILE_SUMMARY_MODEL?.trim() ?? "";
+    const provider = this.deps.config.largeFileSummaryProvider;
+    const model = this.deps.config.largeFileSummaryModel;
     if (!provider || !model) {
       return undefined;
     }

package/src/summarize.ts

@@ -338,12 +338,10 @@ export async function createLcmSummarizeFromLegacyParams(params: {
   const modelHint =
     typeof params.legacyParams.model === "string" ? params.legacyParams.model.trim() : "";
   const modelRef = modelHint || undefined;
-  console.error(`[lcm] createLcmSummarize: providerHint="${providerHint}", modelHint="${modelHint}", modelRef="${modelRef}"`);
 
   let resolved: { provider: string; model: string };
   try {
     resolved = params.deps.resolveModel(modelRef, providerHint || undefined);
-    console.error(`[lcm] createLcmSummarize: resolved model=${resolved.model}, provider=${resolved.provider}`);
   } catch (err) {
     console.error(`[lcm] createLcmSummarize: resolveModel FAILED:`, err instanceof Error ? err.message : err);
     return undefined;