@martian-engineering/lossless-claw 0.11.0 → 0.11.2

package/docs/agent-tools.md

@@ -124,6 +124,7 @@ When `allConversations: true` is set, `lcm_expand_query` can now synthesize one
 | `query` | string | ✅* | — | Text query to find summaries (if no `summaryIds`) |
 | `summaryIds` | string[] | ✅* | — | Specific summary IDs to expand (if no `query`) |
 | `maxTokens` | number | | 2000 | Answer length cap |
+| `timeoutMs` | number | ✅ | `delegationTimeoutMs + 30000` | Total OpenClaw dynamic tool RPC timeout; use the schema default so delegated recall can finish before the host watchdog fires |
 | `conversationId` | number | | current session family | Scope to a specific physical conversation |
 | `allConversations` | boolean | | `false` | Search across all conversations |
 
@@ -144,20 +145,23 @@ When `allConversations: true` is set, `lcm_expand_query` can now synthesize one
 # Find and expand summaries about a topic
 lcm_expand_query(
   query: "OAuth authentication fix",
-  prompt: "What was the root cause and what commits fixed it?"
+  prompt: "What was the root cause and what commits fixed it?",
+  timeoutMs: 150000
 )
 
 # Expand specific summaries you already have
 lcm_expand_query(
   summaryIds: ["sum_abc123", "sum_def456"],
-  prompt: "What were the exact file changes?"
+  prompt: "What were the exact file changes?",
+  timeoutMs: 150000
 )
 
 # Cross-conversation synthesis
 lcm_expand_query(
   query: "deployment procedure",
   prompt: "What's the current deployment process?",
-  allConversations: true
+  allConversations: true,
+  timeoutMs: 150000
 )
 ```
 
@@ -193,6 +197,6 @@ By default, tools operate on the current session family: the active conversation
 
 - `lcm_grep` and `lcm_describe` are fast (direct database queries)
 - `lcm_expand_query` spawns a sub-agent and takes ~30–120 seconds
-- The sub-agent has a 120-second timeout with cleanup guarantees
+- The sub-agent has a 120-second timeout with cleanup guarantees by default, and the tool schema advertises a 150-second OpenClaw dynamic RPC timeout so the host watchdog stays open long enough for delegated recall plus result cleanup
 - Token caps (`LCM_MAX_EXPAND_TOKENS`) prevent runaway expansion
 - Cross-conversation `lcm_expand_query` expands only a bounded set of top-ranked conversations

package/docs/configuration.md

@@ -33,6 +33,9 @@ Most installations only need to override a handful of keys. If you want a comple
   "incrementalMaxDepth": 1,
   "leafChunkTokens": 20000,
   "summaryPrefixTargetTokens": 20000,
+  "maxSweepIterations": 12,
+  "sweepDeadlineMs": 120000,
+  "compactUntilUnderDeadlineMs": 300000,
   "bootstrapMaxTokens": 6000,
   "leafTargetTokens": 2400,
   "condensedTargetTokens": 2000,
@@ -156,6 +159,9 @@ Every automatic decision emits grep-able log lines prefixed with `[lcm] auto-rot
 | `incrementalMaxDepth` | `integer` | alias of `sweepMaxDepth` | `LCM_INCREMENTAL_MAX_DEPTH` | Deprecated alias for `sweepMaxDepth`. Kept so existing configs continue to load. |
 | `leafChunkTokens` | `integer` | `20000` | `LCM_LEAF_CHUNK_TOKENS` | Maximum source-token budget for a leaf compaction chunk. Larger chunks reduce sweep frequency at the cost of slower individual summary calls. |
 | `summaryPrefixTargetTokens` | `integer` | derived | `LCM_SUMMARY_PREFIX_TARGET_TOKENS` | Optional target for summarized-prefix tokens after a full sweep. If unset, Lossless derives `max(condensedTargetTokens, min(leafChunkTokens, floor(contextThreshold * tokenBudget * 0.5)))`. |
+| `maxSweepIterations` | `integer` | `12` | `LCM_MAX_SWEEP_ITERATIONS` | Hard cap on summarizer passes within a single full sweep. On hitting the cap the sweep stops cleanly and returns the partial result; bounds how long a sweep can run on the turn-critical path. |
+| `sweepDeadlineMs` | `integer` | `120000` | `LCM_SWEEP_DEADLINE_MS` | Wall-clock budget for a single full sweep, in milliseconds. When exceeded the sweep stops before starting another pass, so a slow or rate-limited summarizer cannot hang the agent turn. |
+| `compactUntilUnderDeadlineMs` | `integer` | `300000` | `LCM_COMPACT_UNTIL_UNDER_DEADLINE_MS` | Wall-clock budget for a whole `compactUntilUnder` operation, in milliseconds. `compactUntilUnder` runs up to `maxRounds` sweeps; without this the worst case is `maxRounds × sweepDeadlineMs` (~20 min at the defaults). The deadline is shared into each round's sweep and checked before the next round. |
 | `bootstrapMaxTokens` | `integer` | `max(6000, floor(leafChunkTokens * 0.3))` | `LCM_BOOTSTRAP_MAX_TOKENS` | Maximum parent-history tokens imported when a new LCM conversation bootstraps. |
 | `leafTargetTokens` | `integer` | `2400` | `LCM_LEAF_TARGET_TOKENS` | Prompt target for leaf summary size. |
 | `condensedTargetTokens` | `integer` | `2000` | `LCM_CONDENSED_TARGET_TOKENS` | Prompt target for condensed summary size. |
@@ -175,7 +181,7 @@ Every automatic decision emits grep-able log lines prefixed with `[lcm] auto-rot
 | `largeFileSummaryProvider` | `string` | `""` | `LCM_LARGE_FILE_SUMMARY_PROVIDER` | Large-file summarizer provider hint for bare model names. |
 | `expansionModel` | `string` | `""` | `LCM_EXPANSION_MODEL` | `lcm_expand_query` sub-agent model override. |
 | `expansionProvider` | `string` | `""` | `LCM_EXPANSION_PROVIDER` | `lcm_expand_query` sub-agent provider hint for bare model names. |
-| `delegationTimeoutMs` | `integer` | `120000` | `LCM_DELEGATION_TIMEOUT_MS` | Maximum time to wait for delegated expansion work. |
+| `delegationTimeoutMs` | `integer` | `120000` | `LCM_DELEGATION_TIMEOUT_MS` | Maximum time to wait for delegated expansion work. `lcm_expand_query` advertises a dynamic tool `timeoutMs` default with 30 seconds of extra RPC headroom so OpenClaw's tool watchdog does not fire before this wait completes. |
 | `summaryTimeoutMs` | `integer` | `60000` | `LCM_SUMMARY_TIMEOUT_MS` | Maximum time to wait for one model-backed summarizer call. |
 | `customInstructions` | `string` | `""` | `LCM_CUSTOM_INSTRUCTIONS` | Extra natural-language instructions injected into every summarization prompt. |
 
@@ -223,6 +229,10 @@ Lossless still records prompt-cache telemetry for status and diagnostics, but ca
 
 Full sweeps first run leaf passes until there are no more eligible raw-message chunks outside the fresh tail. Condensation is then driven by summarized-prefix pressure: the routine condensation phase obeys `sweepMaxDepth`, and if the summarized prefix still exceeds `summaryPrefixTargetTokens`, a pressure phase may use `condensedMinFanoutHard` and condense deeper. Total context pressure starts the sweep, but does not by itself force deeper condensation once the raw prefix has been summarized.
 
+A single sweep is bounded by both `maxSweepIterations` (a hard cap on summarizer passes) and `sweepDeadlineMs` (a wall-clock budget). When either limit is reached the sweep stops before starting another pass and returns the consistent partial result built so far, logging a `compactFullSweep stopped at …` warning. This keeps a slow or rate-limited summarizer from hanging the agent turn — remaining context pressure is picked up by the next sweep.
+
+Overflow recovery (`compactUntilUnder`) runs up to `maxRounds` sweeps to drive context under a target. Because every sweep re-arms its own `sweepDeadlineMs`, the whole operation is separately bounded by `compactUntilUnderDeadlineMs` (default 300000): the operation deadline is shared into each round's sweep — a sweep stops at whichever deadline is sooner — and is also checked before starting the next round. On hitting it, `compactUntilUnder` returns the consistent partial result and logs a `compactUntilUnder stopped at …` warning, so the worst case is the operation budget rather than `maxRounds × sweepDeadlineMs`.
+
 ### Prompt-aware eviction
 
 When `promptAwareEviction` is enabled:

package/openclaw.plugin.json

@@ -56,6 +56,18 @@
       "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."
     },
+    "maxSweepIterations": {
+      "label": "Max Sweep Iterations",
+      "help": "Hard cap on summarizer passes within a single full compaction sweep (default 12). Bounds how long a sweep can run on the turn-critical path; on hitting the cap the sweep stops cleanly with a partial result."
+    },
+    "sweepDeadlineMs": {
+      "label": "Sweep Deadline (ms)",
+      "help": "Wall-clock budget for a single full compaction sweep, in milliseconds (default 120000). When exceeded the sweep stops before starting another pass, so a slow or rate-limited summarizer cannot hang the agent turn."
+    },
+    "compactUntilUnderDeadlineMs": {
+      "label": "Compact-Until-Under Deadline (ms)",
+      "help": "Wall-clock budget for a whole compact-until-under operation, in milliseconds (default 300000). A compact-until-under run executes several sweeps; this caps the total so it cannot run maxRounds times the per-sweep deadline (~20 minutes at defaults)."
+    },
     "bootstrapMaxTokens": {
       "label": "Bootstrap Max Tokens",
       "help": "Maximum raw parent-history tokens imported into a brand-new conversation bootstrap; oldest turns are dropped first"
@@ -295,6 +307,18 @@
         "type": "integer",
         "minimum": 1
       },
+      "maxSweepIterations": {
+        "type": "integer",
+        "minimum": 1
+      },
+      "sweepDeadlineMs": {
+        "type": "integer",
+        "minimum": 1
+      },
+      "compactUntilUnderDeadlineMs": {
+        "type": "integer",
+        "minimum": 1
+      },
       "bootstrapMaxTokens": {
         "type": "integer",
         "minimum": 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martian-engineering/lossless-claw",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "Lossless Context Management plugin for OpenClaw — DAG-based conversation summarization with threshold compaction",
   "type": "module",
   "main": "dist/index.js",

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

@@ -163,6 +163,36 @@ Why it matters:
 - When unset, Lossless derives a target from `contextThreshold`, the active token budget, and `leafChunkTokens`.
 - Sweeps first exhaust eligible raw-message leaf chunks, then honor `sweepMaxDepth`; pressure condensation can go deeper only when summary-prefix pressure remains.
 
+### `maxSweepIterations`
+
+Hard cap on summarizer passes within a single full sweep. Default `12`.
+
+Why it matters:
+
+- A large conversation can otherwise drive an unbounded number of leaf/condensed passes in one sweep.
+- On hitting the cap the sweep stops cleanly and returns the partial result; the next sweep resumes the remaining work.
+- Bounds how long a sweep can run on the turn-critical path (the `assemble()` deferred-debt drain).
+
+### `sweepDeadlineMs`
+
+Wall-clock budget for a single full sweep, in milliseconds. Default `120000`.
+
+Why it matters:
+
+- A slow or rate-limited summarizer can burn a full `summaryTimeoutMs` per pass; without a deadline, many passes compound into tens of minutes.
+- When the deadline is exceeded the sweep stops before starting another pass and returns the partial result.
+- Pairs with `maxSweepIterations`: whichever limit is reached first stops the sweep.
+
+### `compactUntilUnderDeadlineMs`
+
+Wall-clock budget for a whole `compactUntilUnder` (overflow recovery) operation, in milliseconds. Default `300000`.
+
+Why it matters:
+
+- `compactUntilUnder` runs up to `maxRounds` sweeps, and each sweep re-arms its own `sweepDeadlineMs`; without an operation-wide budget the worst case is `maxRounds × sweepDeadlineMs` (~20 minutes at the defaults).
+- The deadline is shared into each round's sweep — a sweep stops at whichever deadline is sooner — and is also checked before starting the next round.
+- On hitting it, `compactUntilUnder` returns the consistent partial result; the default leaves room for a few full-deadline sweeps while capping the worst case well below 20 minutes.
+
 ### `incrementalMaxDepth`
 
 Deprecated alias for `sweepMaxDepth`.
@@ -386,6 +416,30 @@ Env override:
 
 - `LCM_SUMMARY_PREFIX_TARGET_TOKENS`
 
+### `maxSweepIterations`
+
+See high-impact settings above.
+
+Env override:
+
+- `LCM_MAX_SWEEP_ITERATIONS`
+
+### `sweepDeadlineMs`
+
+See high-impact settings above.
+
+Env override:
+
+- `LCM_SWEEP_DEADLINE_MS`
+
+### `compactUntilUnderDeadlineMs`
+
+See high-impact settings above.
+
+Env override:
+
+- `LCM_COMPACT_UNTIL_UNDER_DEADLINE_MS`
+
 ### `incrementalMaxDepth`
 
 Deprecated alias for `sweepMaxDepth`.