@martian-engineering/lossless-claw 0.11.3 → 0.13.0

package/README.md

@@ -10,6 +10,7 @@ Lossless Context Management plugin for [OpenClaw](https://github.com/openclaw/op
 - [Commands And Skill](#commands-and-skill)
 - [Documentation](#documentation)
 - [Development](#development)
+- [Security](#security)
 - [License](#license)
 
 ## What it does
@@ -65,7 +66,7 @@ The bundled skill focuses on configuration, diagnostics, architecture, and recal
 - Node.js 22+
 - An LLM provider configured in OpenClaw (used for summarization)
 
-> **Compatibility:** `lossless-claw@0.10.0` and newer require OpenClaw `2026.5.12` or newer. These releases call OpenClaw's `api.runtime.llm.complete` capability for summarization, which is unavailable in older OpenClaw builds. If you cannot upgrade OpenClaw yet, stay on `lossless-claw@0.9.4` and remove `0.10.x`-only config such as `sweepMaxDepth`.
+> **Compatibility:** `lossless-claw@0.10.0` and newer require OpenClaw `2026.5.12` or newer for OpenClaw's `api.runtime.llm.complete` summarization capability. Releases that include context-engine memory supplement support require OpenClaw `2026.5.28` or newer for `buildMemorySystemPromptAddition`. If you cannot upgrade OpenClaw yet, stay on `lossless-claw@0.9.4` and remove `0.10.x`-only config such as `sweepMaxDepth`.
 
 ### Install the plugin
 
@@ -139,6 +140,18 @@ Add a `lossless-claw` entry under `plugins.entries` in your OpenClaw config:
           "leafChunkTokens": 80000,
           "newSessionRetainDepth": 2,
           "contextThreshold": 0.75,
+          "contextThresholdOverrides": [
+            {
+              "name": "large-context-models",
+              "match": { "modelContextWindowMin": 900000 },
+              "contextThreshold": 0.15
+            },
+            {
+              "name": "telegram-sessions",
+              "match": { "sessionPattern": "agent:*:telegram:**" },
+              "contextThreshold": 0.3
+            }
+          ],
           "incrementalMaxDepth": 1,
           "cacheAwareCompaction": {
             "enabled": true,
@@ -152,7 +165,10 @@ Add a `lossless-claw` entry under `plugins.entries` in your OpenClaw config:
           "summaryModel": "openai/gpt-5.4-mini",
           "expansionModel": "openai/gpt-5.4-mini",
           "delegationTimeoutMs": 300000,
-          "summaryTimeoutMs": 60000
+          "summaryTimeoutMs": 60000,
+          "summaryCallWindowMs": 600000,
+          "summaryMaxCallsPerWindow": 24,
+          "summarySpendBackoffMs": 1800000
         }
       }
     }
@@ -160,7 +176,7 @@ Add a `lossless-claw` entry under `plugins.entries` in your OpenClaw config:
 }
 ```
 
-`leafChunkTokens` controls how many source tokens can accumulate in a leaf compaction chunk before summarization is triggered. The default is `20000`, but quota-limited summary providers may benefit from a larger value to reduce compaction frequency. `summaryModel` and `summaryProvider` let you request a cheaper or faster compaction model through OpenClaw's `api.runtime.llm.complete` capability; OpenClaw still owns provider dispatch and auth. Explicit summary model requests require `llm.allowModelOverride` and matching `llm.allowedModels` policy entries for `lossless-claw`. `expansionModel` does the same for `lcm_expand_query` sub-agent calls (drilling into summaries to recover detail). `delegationTimeoutMs` controls how long `lcm_expand_query` waits for that delegated sub-agent to finish before returning a timeout error; it defaults to `120000` (120s). `summaryTimeoutMs` controls the per-call timeout for model-backed LCM summarization; it defaults to `60000` (60s). When unset, the model settings still fall back to OpenClaw's configured default model/provider. See [Expansion model override requirements](#expansion-model-override-requirements) for the required `subagent` trust policy when using `expansionModel`.
+`leafChunkTokens` controls how many source tokens can accumulate in a leaf compaction chunk before summarization is triggered. The default is `20000`, but quota-limited summary providers may benefit from a larger value to reduce compaction frequency. `summaryModel` and `summaryProvider` let you request a cheaper or faster compaction model through OpenClaw's `api.runtime.llm.complete` capability; OpenClaw still owns provider dispatch and auth. Explicit summary model requests require `llm.allowModelOverride` and matching `llm.allowedModels` policy entries for `lossless-claw`. `expansionModel` does the same for `lcm_expand_query` sub-agent calls (drilling into summaries to recover detail). `delegationTimeoutMs` controls how long `lcm_expand_query` waits for that delegated sub-agent to finish before returning a timeout error; it defaults to `120000` (120s). `summaryTimeoutMs` controls the per-call timeout for model-backed LCM summarization; it defaults to `60000` (60s). `summaryMaxCallsPerWindow`, `summaryCallWindowMs`, and `summarySpendBackoffMs` bound repeated non-auth summarization spend per session. When unset, the model settings still fall back to OpenClaw's configured default model/provider. See [Expansion model override requirements](#expansion-model-override-requirements) for the required `subagent` trust policy when using `expansionModel`.
 
 ### Environment variables
 
@@ -192,6 +208,9 @@ Add a `lossless-claw` entry under `plugins.entries` in your OpenClaw config:
 | `LCM_EXPANSION_PROVIDER` | *(from OpenClaw)* | Provider override for `lcm_expand_query` sub-agent |
 | `LCM_DELEGATION_TIMEOUT_MS` | `120000` | Max time to wait for delegated `lcm_expand_query` sub-agent completion |
 | `LCM_SUMMARY_TIMEOUT_MS` | `60000` | Max time to wait for a single model-backed LCM summarizer call |
+| `LCM_SUMMARY_CALL_WINDOW_MS` | `600000` | Rolling window used by the per-session summarization spend guard |
+| `LCM_SUMMARY_MAX_CALLS_PER_WINDOW` | `24` | Max model-backed summarization calls per session/window before spend backoff opens |
+| `LCM_SUMMARY_SPEND_BACKOFF_MS` | `1800000` | Cooldown after the summarization spend guard opens |
 | `LCM_PRUNE_HEARTBEAT_OK` | `false` | Retroactively delete `HEARTBEAT_OK` turn cycles from LCM storage |
 | `LCM_TRANSCRIPT_GC_ENABLED` | `false` | Enable transcript rewrite GC during `maintain()` |
 | `LCM_PROACTIVE_THRESHOLD_COMPACTION_MODE` | `deferred` | Choose whether proactive threshold compaction is deferred into maintenance debt or kept inline for legacy behavior |
@@ -278,6 +297,7 @@ LCM_EXPANSION_MODEL=openai/gpt-5.4-mini
 - **leafChunkTokens=20000** limits how large each leaf compaction chunk can grow before LCM summarizes it. Increase this when your summary provider is quota-limited and frequent leaf compactions are exhausting that quota.
 - **incrementalMaxDepth=1** runs one condensed pass after each leaf compaction by default. Set to `0` for leaf-only behavior, a larger positive integer for a deeper cap, or `-1` for unlimited cascading.
 - **contextThreshold=0.75** triggers compaction when context reaches 75% of the model's window, leaving headroom for the model's response.
+- **contextThresholdOverrides** optionally picks a different threshold for matching model ids, model context-window ranges, or session patterns. If no rule matches, LCM falls back to `contextThreshold`.
 
 ### Session exclusion patterns
 
@@ -293,7 +313,7 @@ For large sessions, neither command is a perfect “keep my live agent context,
 - `/new` keeps writing into the same active LCM conversation row.
 - `/reset` changes OpenClaw session flow, which is heavier than users often want when their real problem is just LCM row size.
 
-`/lcm rotate` fills that gap. It replaces one rolling `rotate-latest` SQLite backup, rewrites the current session transcript down to the preserved live tail plus current session settings, and refreshes the bootstrap frontier on the same active LCM conversation so dropped transcript history is not replayed. Existing summaries, context items, and conversation identity stay in place; only the transcript backing is compacted. If you want additional timestamped snapshots instead, run `/lcm backup`.
+`/lcm rotate` fills that gap. Before trimming the transcript, it forces leaf-only compaction for raw context outside the preserved live tail so older transcript messages are represented by LCM summaries. It then replaces one rolling `rotate-latest` SQLite backup, rewrites the current session transcript down to the preserved live tail plus current session settings, and refreshes the bootstrap frontier on the same active LCM conversation so dropped transcript history is not replayed. Existing durable messages, summaries, context items, and conversation identity stay in place; only the transcript backing is compacted. If you want additional timestamped snapshots instead, run `/lcm backup`.
 
 `newSessionRetainDepth` (or `LCM_NEW_SESSION_RETAIN_DEPTH`) controls how much summary structure survives `/new`:
 
@@ -307,6 +327,8 @@ Lossless-claw applies `/new` pruning through `before_reset` and uses `session_en
 
 Use `ignoreSessionPatterns` or `LCM_IGNORE_SESSION_PATTERNS` to keep low-value sessions completely out of LCM. Matching sessions do not create conversations, do not store messages, and do not participate in compaction or delegated expansion grants.
 
+Cron scheduler keys (`agent:<agent>:cron:<job>...`) are isolated automatically when OpenClaw reuses the same `sessionKey` for a new runtime `sessionId`: lossless-claw archives the prior active run and creates a fresh LCM conversation for the new run. Leave cron sessions out of `ignoreSessionPatterns` when they need in-run LCM compaction.
+
 Pattern rules:
 
 - `*` matches any characters except `:`
@@ -315,7 +337,7 @@ Pattern rules:
 
 Examples:
 
-- `agent:*:cron:**` excludes cron sessions for any agent, including isolated run sessions like `agent:main:cron:daily-digest:run:run-123`
+- `agent:*:cron:**` excludes cron sessions for any agent when you want to bypass LCM entirely
 - `agent:main:subagent:**` excludes all main-agent subagent sessions
 - `agent:ops:**` excludes every session under the `ops` agent id
 
@@ -497,6 +519,11 @@ tui/                        # Interactive terminal UI (Go)
 .goreleaser.yml             # GoReleaser config for TUI binary releases
 ```
 
+## Security
+
+Please report suspected vulnerabilities privately. See [SECURITY.md](SECURITY.md)
+for the supported disclosure process and response expectations.
+
 ## License
 
 MIT