From 326490ab768820bccc4ac2eb3b7eea7a1d27e276 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 2 Apr 2026 10:23:25 +0900 Subject: [PATCH] docs: cover compaction notifyUser config and provider replay hooks --- docs/concepts/compaction.md | 20 ++++++++++++++++++++ docs/gateway/configuration-reference.md | 2 ++ docs/plugins/architecture.md | 5 ++++- docs/plugins/sdk-provider-plugins.md | 3 +++ 4 files changed, 29 insertions(+), 1 deletion(-) diff --git a/docs/concepts/compaction.md b/docs/concepts/compaction.md index 91a1bdb89f0..cf69945358b 100644 --- a/docs/concepts/compaction.md +++ b/docs/concepts/compaction.md @@ -58,6 +58,26 @@ capable model for better summaries: } ``` +## Compaction start notice + +By default, compaction runs silently. To show a brief notice when compaction +starts, enable `notifyUser`: + +```json5 +{ + agents: { + defaults: { + compaction: { + notifyUser: true, + }, + }, + }, +} +``` + +When enabled, the user sees a short message (for example, "Compacting +context...") at the start of each compaction run. + ## Compaction vs pruning | | Compaction | Pruning | diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index dfa06043ef8..880823bb6fe 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -1064,6 +1064,7 @@ Periodic heartbeat runs. identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override + notifyUser: true, // send a brief notice when compaction starts (default: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -1082,6 +1083,7 @@ Periodic heartbeat runs. - `identifierInstructions`: optional custom identifier-preservation text used when `identifierPolicy=custom`. - `postCompactionSections`: optional AGENTS.md H2/H3 section names to re-inject after compaction. Defaults to `["Session Startup", "Red Lines"]`; set `[]` to disable reinjection. When unset or explicitly set to that default pair, older `Every Session`/`Safety` headings are also accepted as a legacy fallback. - `model`: optional `provider/model-id` override for compaction summarization only. Use this when the main session should keep one model but compaction summaries should run on another; when unset, compaction uses the session's primary model. +- `notifyUser`: when `true`, sends a brief notice to the user when compaction starts (for example, "Compacting context..."). Disabled by default to keep compaction silent. - `memoryFlush`: silent agentic turn before auto-compaction to store durable memories. Skipped when workspace is read-only. ### `agents.defaults.contextPruning` diff --git a/docs/plugins/architecture.md b/docs/plugins/architecture.md index 27c76c66c30..699be202fe9 100644 --- a/docs/plugins/architecture.md +++ b/docs/plugins/architecture.md @@ -590,7 +590,7 @@ Provider plugins now have two layers: runtime load, plus `providerAuthChoices` for cheap onboarding/auth-choice labels and CLI flag metadata before runtime load - config-time hooks: `catalog` / legacy `discovery` -- runtime hooks: `resolveDynamicModel`, `prepareDynamicModel`, `normalizeResolvedModel`, `capabilities`, `prepareExtraParams`, `wrapStreamFn`, `formatApiKey`, `refreshOAuth`, `buildAuthDoctorHint`, `isCacheTtlEligible`, `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `isBinaryThinking`, `supportsXHighThinking`, `resolveDefaultThinkingLevel`, `isModernModelRef`, `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot` +- runtime hooks: `resolveDynamicModel`, `prepareDynamicModel`, `normalizeResolvedModel`, `capabilities`, `prepareExtraParams`, `wrapStreamFn`, `formatApiKey`, `refreshOAuth`, `buildAuthDoctorHint`, `isCacheTtlEligible`, `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `isBinaryThinking`, `supportsXHighThinking`, `resolveDefaultThinkingLevel`, `isModernModelRef`, `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns` OpenClaw still owns the generic agent loop, failover, transcript handling, and tool policy. These hooks are the extension surface for provider-specific behavior without @@ -633,6 +633,9 @@ The "When to use" column is the quick decision guide. | 19 | `prepareRuntimeAuth` | Exchange a configured credential into the actual runtime token/key just before inference | Provider needs a token exchange or short-lived request credential | | 20 | `resolveUsageAuth` | Resolve usage/billing credentials for `/usage` and related status surfaces | Provider needs custom usage/quota token parsing or a different usage credential | | 21 | `fetchUsageSnapshot` | Fetch and normalize provider-specific usage/quota snapshots after auth is resolved | Provider needs a provider-specific usage endpoint or payload parser | +| 22 | `buildReplayPolicy` | Return a replay policy controlling transcript handling for the provider | Provider needs custom transcript policy (for example, thinking-block stripping) | +| 23 | `sanitizeReplayHistory` | Rewrite replay history after generic transcript cleanup | Provider needs provider-specific replay rewrites beyond shared compaction helpers | +| 24 | `validateReplayTurns` | Final replay-turn validation or reshaping before the embedded runner | Provider transport needs stricter turn validation after generic sanitation | If the provider needs a fully custom wire protocol or custom request executor, that is a different class of extension. These hooks are for provider behavior diff --git a/docs/plugins/sdk-provider-plugins.md b/docs/plugins/sdk-provider-plugins.md index 86a7c4f0546..afeddcab209 100644 --- a/docs/plugins/sdk-provider-plugins.md +++ b/docs/plugins/sdk-provider-plugins.md @@ -312,6 +312,9 @@ API key auth, and dynamic model resolution. | 20 | `resolveUsageAuth` | Custom usage credential parsing | | 21 | `fetchUsageSnapshot` | Custom usage endpoint | | 22 | `onModelSelected` | Post-selection callback (e.g. telemetry) | + | 23 | `buildReplayPolicy` | Custom transcript policy (e.g. thinking-block stripping) | + | 24 | `sanitizeReplayHistory` | Provider-specific replay rewrites after generic cleanup | + | 25 | `validateReplayTurns` | Strict replay-turn validation before the embedded runner | For detailed descriptions and real-world examples, see [Internals: Provider Runtime Hooks](/plugins/architecture#provider-runtime-hooks).