fix: satisfy lint curly rule (#6310)
* fix: satisfy lint curly rule * docs: apply oxfmt formattingmain
parent
8582ed4d4f
commit
e9f70e8585
|
|
@ -21,6 +21,7 @@ This folder stores **generated** and **config** files for documentation translat
|
||||||
```
|
```
|
||||||
|
|
||||||
Fields:
|
Fields:
|
||||||
|
|
||||||
- `source`: English (or source) phrase to prefer.
|
- `source`: English (or source) phrase to prefer.
|
||||||
- `target`: preferred translation output.
|
- `target`: preferred translation output.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -4,29 +4,34 @@ read_when:
|
||||||
- You want to reduce LLM context growth from tool outputs
|
- You want to reduce LLM context growth from tool outputs
|
||||||
- You are tuning agents.defaults.contextPruning
|
- You are tuning agents.defaults.contextPruning
|
||||||
---
|
---
|
||||||
|
|
||||||
# Session Pruning
|
# Session Pruning
|
||||||
|
|
||||||
Session pruning trims **old tool results** from the in-memory context right before each LLM call. It does **not** rewrite the on-disk session history (`*.jsonl`).
|
Session pruning trims **old tool results** from the in-memory context right before each LLM call. It does **not** rewrite the on-disk session history (`*.jsonl`).
|
||||||
|
|
||||||
## When it runs
|
## When it runs
|
||||||
|
|
||||||
- When `mode: "cache-ttl"` is enabled and the last Anthropic call for the session is older than `ttl`.
|
- When `mode: "cache-ttl"` is enabled and the last Anthropic call for the session is older than `ttl`.
|
||||||
- Only affects the messages sent to the model for that request.
|
- Only affects the messages sent to the model for that request.
|
||||||
- Only active for Anthropic API calls (and OpenRouter Anthropic models).
|
- Only active for Anthropic API calls (and OpenRouter Anthropic models).
|
||||||
- For best results, match `ttl` to your model `cacheControlTtl`.
|
- For best results, match `ttl` to your model `cacheControlTtl`.
|
||||||
- After a prune, the TTL window resets so subsequent requests keep cache until `ttl` expires again.
|
- After a prune, the TTL window resets so subsequent requests keep cache until `ttl` expires again.
|
||||||
|
|
||||||
## Smart defaults (Anthropic)
|
## Smart defaults (Anthropic)
|
||||||
|
|
||||||
- **OAuth or setup-token** profiles: enable `cache-ttl` pruning and set heartbeat to `1h`.
|
- **OAuth or setup-token** profiles: enable `cache-ttl` pruning and set heartbeat to `1h`.
|
||||||
- **API key** profiles: enable `cache-ttl` pruning, set heartbeat to `30m`, and default `cacheControlTtl` to `1h` on Anthropic models.
|
- **API key** profiles: enable `cache-ttl` pruning, set heartbeat to `30m`, and default `cacheControlTtl` to `1h` on Anthropic models.
|
||||||
- If you set any of these values explicitly, OpenClaw does **not** override them.
|
- If you set any of these values explicitly, OpenClaw does **not** override them.
|
||||||
|
|
||||||
## What this improves (cost + cache behavior)
|
## What this improves (cost + cache behavior)
|
||||||
|
|
||||||
- **Why prune:** Anthropic prompt caching only applies within the TTL. If a session goes idle past the TTL, the next request re-caches the full prompt unless you trim it first.
|
- **Why prune:** Anthropic prompt caching only applies within the TTL. If a session goes idle past the TTL, the next request re-caches the full prompt unless you trim it first.
|
||||||
- **What gets cheaper:** pruning reduces the **cacheWrite** size for that first request after the TTL expires.
|
- **What gets cheaper:** pruning reduces the **cacheWrite** size for that first request after the TTL expires.
|
||||||
- **Why the TTL reset matters:** once pruning runs, the cache window resets, so follow‑up requests can reuse the freshly cached prompt instead of re-caching the full history again.
|
- **Why the TTL reset matters:** once pruning runs, the cache window resets, so follow‑up requests can reuse the freshly cached prompt instead of re-caching the full history again.
|
||||||
- **What it does not do:** pruning doesn’t add tokens or “double” costs; it only changes what gets cached on that first post‑TTL request.
|
- **What it does not do:** pruning doesn’t add tokens or “double” costs; it only changes what gets cached on that first post‑TTL request.
|
||||||
|
|
||||||
## What can be pruned
|
## What can be pruned
|
||||||
|
|
||||||
- Only `toolResult` messages.
|
- Only `toolResult` messages.
|
||||||
- User + assistant messages are **never** modified.
|
- User + assistant messages are **never** modified.
|
||||||
- The last `keepLastAssistants` assistant messages are protected; tool results after that cutoff are not pruned.
|
- The last `keepLastAssistants` assistant messages are protected; tool results after that cutoff are not pruned.
|
||||||
|
|
@ -34,35 +39,43 @@ Session pruning trims **old tool results** from the in-memory context right befo
|
||||||
- Tool results containing **image blocks** are skipped (never trimmed/cleared).
|
- Tool results containing **image blocks** are skipped (never trimmed/cleared).
|
||||||
|
|
||||||
## Context window estimation
|
## Context window estimation
|
||||||
|
|
||||||
Pruning uses an estimated context window (chars ≈ tokens × 4). The base window is resolved in this order:
|
Pruning uses an estimated context window (chars ≈ tokens × 4). The base window is resolved in this order:
|
||||||
1) `models.providers.*.models[].contextWindow` override.
|
|
||||||
2) Model definition `contextWindow` (from the model registry).
|
1. `models.providers.*.models[].contextWindow` override.
|
||||||
3) Default `200000` tokens.
|
2. Model definition `contextWindow` (from the model registry).
|
||||||
|
3. Default `200000` tokens.
|
||||||
|
|
||||||
If `agents.defaults.contextTokens` is set, it is treated as a cap (min) on the resolved window.
|
If `agents.defaults.contextTokens` is set, it is treated as a cap (min) on the resolved window.
|
||||||
|
|
||||||
## Mode
|
## Mode
|
||||||
|
|
||||||
### cache-ttl
|
### cache-ttl
|
||||||
|
|
||||||
- Pruning only runs if the last Anthropic call is older than `ttl` (default `5m`).
|
- Pruning only runs if the last Anthropic call is older than `ttl` (default `5m`).
|
||||||
- When it runs: same soft-trim + hard-clear behavior as before.
|
- When it runs: same soft-trim + hard-clear behavior as before.
|
||||||
|
|
||||||
## Soft vs hard pruning
|
## Soft vs hard pruning
|
||||||
|
|
||||||
- **Soft-trim**: only for oversized tool results.
|
- **Soft-trim**: only for oversized tool results.
|
||||||
- Keeps head + tail, inserts `...`, and appends a note with the original size.
|
- Keeps head + tail, inserts `...`, and appends a note with the original size.
|
||||||
- Skips results with image blocks.
|
- Skips results with image blocks.
|
||||||
- **Hard-clear**: replaces the entire tool result with `hardClear.placeholder`.
|
- **Hard-clear**: replaces the entire tool result with `hardClear.placeholder`.
|
||||||
|
|
||||||
## Tool selection
|
## Tool selection
|
||||||
|
|
||||||
- `tools.allow` / `tools.deny` support `*` wildcards.
|
- `tools.allow` / `tools.deny` support `*` wildcards.
|
||||||
- Deny wins.
|
- Deny wins.
|
||||||
- Matching is case-insensitive.
|
- Matching is case-insensitive.
|
||||||
- Empty allow list => all tools allowed.
|
- Empty allow list => all tools allowed.
|
||||||
|
|
||||||
## Interaction with other limits
|
## Interaction with other limits
|
||||||
|
|
||||||
- Built-in tools already truncate their own output; session pruning is an extra layer that prevents long-running chats from accumulating too much tool output in the model context.
|
- Built-in tools already truncate their own output; session pruning is an extra layer that prevents long-running chats from accumulating too much tool output in the model context.
|
||||||
- Compaction is separate: compaction summarizes and persists, pruning is transient per request. See [/concepts/compaction](/concepts/compaction).
|
- Compaction is separate: compaction summarizes and persists, pruning is transient per request. See [/concepts/compaction](/concepts/compaction).
|
||||||
|
|
||||||
## Defaults (when enabled)
|
## Defaults (when enabled)
|
||||||
|
|
||||||
- `ttl`: `"5m"`
|
- `ttl`: `"5m"`
|
||||||
- `keepLastAssistants`: `3`
|
- `keepLastAssistants`: `3`
|
||||||
- `softTrimRatio`: `0.3`
|
- `softTrimRatio`: `0.3`
|
||||||
|
|
@ -72,33 +85,37 @@ If `agents.defaults.contextTokens` is set, it is treated as a cap (min) on the r
|
||||||
- `hardClear`: `{ enabled: true, placeholder: "[Old tool result content cleared]" }`
|
- `hardClear`: `{ enabled: true, placeholder: "[Old tool result content cleared]" }`
|
||||||
|
|
||||||
## Examples
|
## Examples
|
||||||
|
|
||||||
Default (off):
|
Default (off):
|
||||||
|
|
||||||
```json5
|
```json5
|
||||||
{
|
{
|
||||||
agent: {
|
agent: {
|
||||||
contextPruning: { mode: "off" }
|
contextPruning: { mode: "off" },
|
||||||
}
|
},
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
Enable TTL-aware pruning:
|
Enable TTL-aware pruning:
|
||||||
|
|
||||||
```json5
|
```json5
|
||||||
{
|
{
|
||||||
agent: {
|
agent: {
|
||||||
contextPruning: { mode: "cache-ttl", ttl: "5m" }
|
contextPruning: { mode: "cache-ttl", ttl: "5m" },
|
||||||
}
|
},
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
Restrict pruning to specific tools:
|
Restrict pruning to specific tools:
|
||||||
|
|
||||||
```json5
|
```json5
|
||||||
{
|
{
|
||||||
agent: {
|
agent: {
|
||||||
contextPruning: {
|
contextPruning: {
|
||||||
mode: "cache-ttl",
|
mode: "cache-ttl",
|
||||||
tools: { allow: ["exec", "read"], deny: ["*image*"] }
|
tools: { allow: ["exec", "read"], deny: ["*image*"] },
|
||||||
}
|
},
|
||||||
}
|
},
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -11,7 +11,9 @@ export type ContextWindowInfo = {
|
||||||
};
|
};
|
||||||
|
|
||||||
function normalizePositiveInt(value: unknown): number | null {
|
function normalizePositiveInt(value: unknown): number | null {
|
||||||
if (typeof value !== "number" || !Number.isFinite(value)) return null;
|
if (typeof value !== "number" || !Number.isFinite(value)) {
|
||||||
|
return null;
|
||||||
|
}
|
||||||
const int = Math.floor(value);
|
const int = Math.floor(value);
|
||||||
return int > 0 ? int : null;
|
return int > 0 ? int : null;
|
||||||
}
|
}
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue