@martian-engineering/lossless-claw 0.9.2 → 0.9.3

package/docs/configuration.md

@@ -55,9 +55,12 @@ Most installations only need to override a handful of keys. If you want a comple
   "proactiveThresholdCompactionMode": "deferred",
   "cacheAwareCompaction": {
     "enabled": true,
+    "cacheTTLSeconds": 300,
     "maxColdCacheCatchupPasses": 2,
     "hotCachePressureFactor": 4,
-    "hotCacheBudgetHeadroomRatio": 0.2
+    "hotCacheBudgetHeadroomRatio": 0.2,
+    "coldCacheObservationThreshold": 3,
+    "criticalBudgetPressureRatio": 0.70
   },
   "dynamicLeafChunkTokens": {
     "enabled": true,
@@ -173,6 +176,7 @@ openclaw plugins install --link /path/to/lossless-claw
 | `cacheAwareCompaction.hotCachePressureFactor` | `number` | `4` | `LCM_HOT_CACHE_PRESSURE_FACTOR` | Multiplier applied to the hot-cache leaf trigger before raw-history pressure overrides cache preservation. |
 | `cacheAwareCompaction.hotCacheBudgetHeadroomRatio` | `number` | `0.2` | `LCM_HOT_CACHE_BUDGET_HEADROOM_RATIO` | Minimum fraction of the real token budget that must remain free before hot-cache incremental compaction is skipped entirely. |
 | `cacheAwareCompaction.coldCacheObservationThreshold` | `integer` | `3` | `LCM_COLD_CACHE_OBSERVATION_THRESHOLD` | Consecutive cold observations required before non-explicit cache misses are treated as truly cold. This dampens one-off routing noise and provider failover blips. |
+| `cacheAwareCompaction.criticalBudgetPressureRatio` | `number` | `0.70` | `LCM_CRITICAL_BUDGET_PRESSURE_RATIO` | Fraction of the token budget at which deferred compaction bypasses hot-cache delay so prompt-mutating debt can run before overflow. Set to `1` to disable this bypass. |
 
 #### `dynamicLeafChunkTokens`
 
@@ -189,6 +193,7 @@ When cache-aware compaction is enabled:
 - hot cache skips incremental maintenance entirely when the assembled context is still comfortably below the real token budget
 - hot cache also gets a short hysteresis window so one ambiguous turn does not immediately discard a recently healthy cache signal
 - cold cache still allows bounded catch-up passes via `cacheAwareCompaction.maxColdCacheCatchupPasses`
+- once `currentTokenCount >= criticalBudgetPressureRatio * tokenBudget`, deferred compaction bypasses hot-cache delay so prompt-mutating debt can run before emergency overflow handling
 
 When incremental leaf compaction still runs on a hot cache, follow-on condensed passes are suppressed so the maintenance cycle only pays for the leaf pass that was explicitly justified.
 

package/docs/tui.md

@@ -245,8 +245,8 @@ Scans for genuinely truncated summaries and can rewrite them in place. This is n
 # Preview repairs for one conversation
 lcm-tui doctor 44 --show-diff
 
-# Apply repairs with an OpenAI-compatible backend
-lcm-tui doctor 44 --apply --provider openai --model gpt-5.3-codex --base-url https://proxy.example.com/openai
+# Apply repairs through Codex CLI OAuth after `codex login`
+lcm-tui doctor 44 --apply --provider openai-codex --model gpt-5.3-codex
 
 # Scan only across every conversation
 lcm-tui doctor --all
@@ -263,6 +263,8 @@ lcm-tui doctor --all
 | `--show-diff` | Show unified diff for each fix |
 | `--timestamps` | Inject timestamps into rewrite source text |
 
+Use `--provider openai-codex` when you want ChatGPT Plus/Pro OAuth from the Codex CLI. Keep `--provider openai` for direct OpenAI-compatible HTTP calls with a raw `OPENAI_API_KEY`, including custom `--base-url` proxies.
+
 ### `lcm-tui repair`
 
 Finds and fixes corrupted summaries (those containing the `[LCM fallback summary]` marker from failed summarization attempts).
@@ -280,7 +282,10 @@ lcm-tui repair 44 --apply
 # Repair a specific summary
 lcm-tui repair 44 --summary-id sum_abc123 --apply
 
-# Repair through an OpenAI-compatible backend
+# Repair through Codex CLI OAuth after `codex login`
+lcm-tui repair 44 --apply --provider openai-codex --model gpt-5.3-codex
+
+# Repair through a custom OpenAI-compatible proxy with a raw API key
 lcm-tui repair 44 --apply --provider openai --model gpt-5.3-codex --base-url https://proxy.example.com/openai
 ```
 
@@ -316,10 +321,10 @@ lcm-tui rewrite 44 --depth 0 --apply
 # Rewrite everything bottom-up
 lcm-tui rewrite 44 --all --apply --diff
 
-# Rewrite with OpenAI Responses API
-lcm-tui rewrite 44 --summary sum_abc123 --provider openai --model gpt-5.3-codex --apply
+# Rewrite with Codex CLI OAuth after `codex login`
+lcm-tui rewrite 44 --summary sum_abc123 --provider openai-codex --model gpt-5.3-codex --apply
 
-# Rewrite through a custom OpenAI-compatible proxy
+# Rewrite through a custom OpenAI-compatible proxy with a raw API key
 lcm-tui rewrite 44 --summary sum_abc123 --provider openai --model gpt-5.3-codex --base-url https://proxy.example.com/openai --apply
 
 # Use custom prompt templates
@@ -412,10 +417,10 @@ lcm-tui backfill my-agent session_abc123 --apply --recompact --single-root
 # Import + compact + transplant into an active conversation
 lcm-tui backfill my-agent session_abc123 --apply --transplant-to 653
 
-# Backfill using OpenAI
-lcm-tui backfill my-agent session_abc123 --apply --provider openai --model gpt-5.3-codex
+# Backfill using Codex CLI OAuth after `codex login`
+lcm-tui backfill my-agent session_abc123 --apply --provider openai-codex --model gpt-5.3-codex
 
-# Backfill through a custom OpenAI-compatible proxy
+# Backfill through a custom OpenAI-compatible proxy with a raw API key
 lcm-tui backfill my-agent session_abc123 --apply --provider openai --model gpt-5.3-codex --base-url https://proxy.example.com/openai
 ```
 

package/openclaw.plugin.json

@@ -4,6 +4,14 @@
   "skills": [
     "skills/lossless-claw"
   ],
+  "contracts": {
+    "tools": [
+      "lcm_grep",
+      "lcm_describe",
+      "lcm_expand",
+      "lcm_expand_query"
+    ]
+  },
   "uiHints": {
     "enabled": {
       "label": "Enabled",
@@ -177,6 +185,10 @@
       "label": "Cold Cache Observation Threshold",
       "help": "Consecutive cold observations required before non-explicit cache misses are treated as truly cold"
     },
+    "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."
+    },
     "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"
@@ -370,6 +382,11 @@
           "coldCacheObservationThreshold": {
             "type": "integer",
             "minimum": 1
+          },
+          "criticalBudgetPressureRatio": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1
           }
         }
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martian-engineering/lossless-claw",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "Lossless Context Management plugin for OpenClaw — DAG-based conversation summarization with incremental compaction",
   "type": "module",
   "main": "dist/index.js",
@@ -31,28 +31,49 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@mariozechner/pi-agent-core": "0.66.1",
-    "@mariozechner/pi-ai": "0.66.1",
-    "@mariozechner/pi-coding-agent": "0.66.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": "*",
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*",
     "openclaw": "*"
   },
+  "peerDependenciesMeta": {
+    "@mariozechner/pi-agent-core": {
+      "optional": true
+    },
+    "@mariozechner/pi-ai": {
+      "optional": true
+    },
+    "@mariozechner/pi-coding-agent": {
+      "optional": true
+    }
+  },
   "publishConfig": {
     "access": "public"
   },
   "openclaw": {
     "extensions": [
       "./dist/index.js"
-    ]
+    ],
+    "compat": {
+      "pluginApi": ">=2026.2.17",
+      "minGatewayVersion": "2026.2.17"
+    },
+    "build": {
+      "openclawVersion": "2026.2.17"
+    }
   },
   "repository": {
     "type": "git",

package/skills/lossless-claw/references/config.md

@@ -103,12 +103,14 @@ Good defaults:
 - `hotCachePressureFactor: 4`
 - `hotCacheBudgetHeadroomRatio: 0.2`
 - `coldCacheObservationThreshold: 3`
+- `criticalBudgetPressureRatio: 0.70`
 
 Operationally:
 
 - hot cache stretches the incremental leaf trigger to `dynamicLeafChunkTokens.max`
 - hot cache skips incremental maintenance entirely when the assembled context is comfortably below the real token budget
 - hot cache gets a short hysteresis window so a recent cache hit stays "hot" briefly unless telemetry shows a break
+- critical token-budget pressure bypasses hot-cache delay once the live prompt reaches `criticalBudgetPressureRatio * tokenBudget`
 - if hot-cache maintenance still runs, it stays leaf-only and suppresses follow-on condensed passes
 
 ### `dynamicLeafChunkTokens`
@@ -428,6 +430,24 @@ Default:
 
 - `3`
 
+#### `cacheAwareCompaction.criticalBudgetPressureRatio`
+
+Fraction of the token budget at which deferred compaction bypasses hot-cache delay.
+
+Why it matters:
+
+- lets prompt-mutating deferred compaction run before the runtime falls back to emergency overflow handling
+- preserves cache-aware throttling below the pressure threshold
+- can be set to `1` to disable this pressure bypass
+
+Default:
+
+- `0.70`
+
+Env override:
+
+- `LCM_CRITICAL_BUDGET_PRESSURE_RATIO`
+
 ### `dynamicLeafChunkTokens`
 
 #### `dynamicLeafChunkTokens.enabled`