From e9f70e858563695c2f9013fb38dba10fb01d239b Mon Sep 17 00:00:00 2001 From: Ayaan Zaidi Date: Sun, 1 Feb 2026 20:04:53 +0530 Subject: [PATCH] fix: satisfy lint curly rule (#6310) * fix: satisfy lint curly rule * docs: apply oxfmt formatting --- docs/.i18n/README.md | 1 + docs/concepts/session-pruning.md | 43 ++++++++++++++++++++--------- docs/zh-CN/index.md | 14 +++++----- docs/zh-CN/start/getting-started.md | 16 +++++------ docs/zh-CN/start/wizard.md | 16 +++++------ src/agents/context-window-guard.ts | 4 ++- 6 files changed, 57 insertions(+), 37 deletions(-) diff --git a/docs/.i18n/README.md b/docs/.i18n/README.md index 3155dff54c6..8e751a11eaa 100644 --- a/docs/.i18n/README.md +++ b/docs/.i18n/README.md @@ -21,6 +21,7 @@ This folder stores **generated** and **config** files for documentation translat ``` Fields: + - `source`: English (or source) phrase to prefer. - `target`: preferred translation output. diff --git a/docs/concepts/session-pruning.md b/docs/concepts/session-pruning.md index 70bf314e934..e9e55b38878 100644 --- a/docs/concepts/session-pruning.md +++ b/docs/concepts/session-pruning.md @@ -4,29 +4,34 @@ read_when: - You want to reduce LLM context growth from tool outputs - You are tuning agents.defaults.contextPruning --- + # 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`). ## When it runs + - 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 active for Anthropic API calls (and OpenRouter Anthropic models). - - 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. +- Only active for Anthropic API calls (and OpenRouter Anthropic models). +- 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. ## Smart defaults (Anthropic) + - **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. - If you set any of these values explicitly, OpenClaw does **not** override them. ## 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. - **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. - **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 + - Only `toolResult` messages. - User + assistant messages are **never** modified. - 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). ## Context window estimation + 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). -3) Default `200000` tokens. + +1. `models.providers.*.models[].contextWindow` override. +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. ## Mode + ### cache-ttl + - 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. ## Soft vs hard pruning + - **Soft-trim**: only for oversized tool results. - Keeps head + tail, inserts `...`, and appends a note with the original size. - Skips results with image blocks. - **Hard-clear**: replaces the entire tool result with `hardClear.placeholder`. ## Tool selection + - `tools.allow` / `tools.deny` support `*` wildcards. - Deny wins. - Matching is case-insensitive. - Empty allow list => all tools allowed. ## 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. - Compaction is separate: compaction summarizes and persists, pruning is transient per request. See [/concepts/compaction](/concepts/compaction). ## Defaults (when enabled) + - `ttl`: `"5m"` - `keepLastAssistants`: `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]" }` ## Examples + Default (off): + ```json5 { agent: { - contextPruning: { mode: "off" } - } + contextPruning: { mode: "off" }, + }, } ``` Enable TTL-aware pruning: + ```json5 { agent: { - contextPruning: { mode: "cache-ttl", ttl: "5m" } - } + contextPruning: { mode: "cache-ttl", ttl: "5m" }, + }, } ``` Restrict pruning to specific tools: + ```json5 { agent: { contextPruning: { mode: "cache-ttl", - tools: { allow: ["exec", "read"], deny: ["*image*"] } - } - } + tools: { allow: ["exec", "read"], deny: ["*image*"] }, + }, + }, } ``` diff --git a/docs/zh-CN/index.md b/docs/zh-CN/index.md index 97f44b4eac7..f158c41ac9a 100644 --- a/docs/zh-CN/index.md +++ b/docs/zh-CN/index.md @@ -1,14 +1,14 @@ --- read_when: - - 向新用户介绍 OpenClaw + - 向新用户介绍 OpenClaw summary: OpenClaw 的顶层概述、功能特性与用途 x-i18n: - generated_at: "2026-02-01T13:34:09Z" - model: claude-opus-4-5 - provider: pi - source_hash: 92462177964ac72c344d3e8613a3756bc8e06eb7844cda20a38cd43e7cadd3b2 - source_path: index.md - workflow: 9 + generated_at: "2026-02-01T13:34:09Z" + model: claude-opus-4-5 + provider: pi + source_hash: 92462177964ac72c344d3e8613a3756bc8e06eb7844cda20a38cd43e7cadd3b2 + source_path: index.md + workflow: 9 --- # OpenClaw 🦞 diff --git a/docs/zh-CN/start/getting-started.md b/docs/zh-CN/start/getting-started.md index 323b41c8c91..123a2fa7d6c 100644 --- a/docs/zh-CN/start/getting-started.md +++ b/docs/zh-CN/start/getting-started.md @@ -1,15 +1,15 @@ --- read_when: - - 从零开始的首次设置 - - 您希望找到从安装 → 上手引导 → 发送第一条消息的最快路径 + - 从零开始的首次设置 + - 您希望找到从安装 → 上手引导 → 发送第一条消息的最快路径 summary: 新手指南：从零开始到发送第一条消息（向导、认证、渠道、配对） x-i18n: - generated_at: "2026-02-01T13:38:44Z" - model: claude-opus-4-5 - provider: pi - source_hash: d0ebc83c10efc569eaf6fb32368a29ef75a373f15da61f3499621462f08aff63 - source_path: start/getting-started.md - workflow: 9 + generated_at: "2026-02-01T13:38:44Z" + model: claude-opus-4-5 + provider: pi + source_hash: d0ebc83c10efc569eaf6fb32368a29ef75a373f15da61f3499621462f08aff63 + source_path: start/getting-started.md + workflow: 9 --- # 快速入门 diff --git a/docs/zh-CN/start/wizard.md b/docs/zh-CN/start/wizard.md index cd02a92df5f..e1f4674441a 100644 --- a/docs/zh-CN/start/wizard.md +++ b/docs/zh-CN/start/wizard.md @@ -1,15 +1,15 @@ --- read_when: - - 运行或配置上手引导向导 - - 设置新机器 + - 运行或配置上手引导向导 + - 设置新机器 summary: CLI 上手引导向导：Gateway、工作区、渠道和技能的引导式设置 x-i18n: - generated_at: "2026-02-01T13:49:20Z" - model: claude-opus-4-5 - provider: pi - source_hash: 571302dcf63a0c700cab6b54964e524d75d98315d3b35fafe7232d2ce8199e83 - source_path: start/wizard.md - workflow: 9 + generated_at: "2026-02-01T13:49:20Z" + model: claude-opus-4-5 + provider: pi + source_hash: 571302dcf63a0c700cab6b54964e524d75d98315d3b35fafe7232d2ce8199e83 + source_path: start/wizard.md + workflow: 9 --- # 上手引导向导 (CLI) diff --git a/src/agents/context-window-guard.ts b/src/agents/context-window-guard.ts index 36d642b708b..1dc38870bf6 100644 --- a/src/agents/context-window-guard.ts +++ b/src/agents/context-window-guard.ts @@ -11,7 +11,9 @@ export type ContextWindowInfo = { }; 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); return int > 0 ? int : null; }