Summary

• AgentCompactionConfig only accepts absolute token counts for reserveTokens, keepRecentTokens, and reserveTokensFloor. The same config therefore behaves very differently on a 32 K Claude 3 Opus model than on a 200 K Claude 3.5 Sonnet model — reserveTokensFloor: 20_000 reserves 62 % of the first context but 10 % of the second, and operators running heterogeneous fleets have to maintain per-model overrides to keep behaviour comparable ([Feature]: Percentage-based compaction config #72790).
• Add three strictly additive optional fields — reserveTokensShare, keepRecentTokensShare, reserveTokensFloorShare — that hold values in (0, 1] and are resolved against the active model's context budget at runtime. The numeric absolute siblings always win when both are set, so existing user configs are byte-identical to current main. When only the share is set and a context budget is known, the absolute value is derived as floor(share * contextTokenBudget). When the share is set but the runtime has no context budget yet (cold-start / unknown model), the resolver falls back to the existing defaults — it never silently returns zero.
• Wire the new resolver into the two existing readers in pi-settings.ts (resolveCompactionReserveTokensFloor, applyPiCompactionSettingsFromConfig); both already accept a contextTokenBudget parameter. The Zod schema gains matching .gt(0).max(1) validators so invalid shares fail fast at config load.

Related Issues

Refs #72790.

Type of Change

• Bug fix
• New feature
• Refactor
• Documentation
• Other (describe below)

Real behavior proof

Behavior or issue addressed: Reporter SERVICEPOP (#72790, 2026-04-27) asked for percentage-based compaction config so the same reserveTokensFloor does not silently mean "62 % of context on Opus, 10 % on Sonnet". ClawSweeper's source-level review confirmed the current numeric-only contract on src/config/types.agent-defaults.ts:484 and src/config/zod-schema.agent-defaults.ts:174, and recommended "Settle one backward-compatible public config API for context-window-relative compaction budgets... while preserving current numeric semantics." This PR lands the additive share-field option the bot's review preferred over percent-string overloading. Existing absolute-token configs are unchanged byte-for-byte; share-based configs resolve at runtime against the active model's context.

Real environment tested: Local Linux checkout of openclaw/openclaw at upstream/main 178a50e017, branched into feat/compaction-budget-shares-72790. Verified by source-level walk: the new fields are declared in AgentCompactionConfig immediately alongside the existing reserveTokens / keepRecentTokens / reserveTokensFloor, the Zod schema accepts them with the same strict shape, and the runtime readers consult them only when the absolute sibling is unset. The applyPiCompactionSettingsFromConfig test suite already exercises the contextTokenBudget threading from auto-reply callers, so the share resolution path is reachable from every existing consumer of the function.

Exact steps or command run after this patch:

git checkout feat/compaction-budget-shares-72790
git diff upstream/main --stat
git diff upstream/main -- src/agents/pi-settings.ts
git diff upstream/main -- src/config/zod-schema.agent-defaults.ts

The first stat shows four files / +203/-5; the per-file diffs show: (a) the new resolveCompactionShareTokens helper + the two-step share-then-absolute fallback in the existing readers; (b) the three new optional fields on the Zod object with .gt(0).max(1) constraints; (c) the matching field declarations on AgentCompactionConfig.

Evidence after fix:

• src/config/types.agent-defaults.ts: AgentCompactionConfig now carries reserveTokensShare?: number, keepRecentTokensShare?: number, reserveTokensFloorShare?: number immediately after the existing absolute-token fields. Each carries a doc comment explaining the (0, 1] range and the absolute-wins precedence.
• src/config/zod-schema.agent-defaults.ts: the compaction object's strict schema accepts the same three fields as z.number().gt(0).max(1).optional(), immediately after reserveTokensFloor and before maxHistoryShare (which already followed the share-field convention).
• src/agents/pi-settings.ts: new resolveCompactionShareTokens(share, contextTokenBudget) exported helper returns floor(share * contextTokenBudget) for valid inputs, undefined otherwise. resolveCompactionReserveTokensFloor and applyPiCompactionSettingsFromConfig both consult the resolver in the order absolute → share → default. The contextTokenBudget parameter that both functions already accepted is now also propagated into the share resolution so floor(0.1 * 200_000) = 20_000 for a 200 K Sonnet caller. All toNonNegativeInt / toPositiveInt integer constraints on the existing absolute paths remain unchanged, and the keep-recent fallback explicitly enforces positive integers (the share resolver result is post-filtered to drop 0).
• src/agents/pi-settings.test.ts: seven new cases (#72790 tag) cover (a) share resolves to absolute when context is known, (b) absolute sibling wins when both set, (c) share ignored when no context budget, (d) keepRecentTokensShare respects positive-int constraint, (e) reserveTokensFloorShare resolves against context budget, (f) absolute floor wins over floor-share, (g) floor-share falls back to default when context budget is unknown. The existing absolute-token tests are unchanged and continue to assert the current byte-identical behaviour.

Observed result after fix: A config that previously needed per-model overrides:

{ "agents": { "defaults": { "compaction": { "reserveTokensFloor": 32000 } } } }   // tuned for Sonnet 200 K (16 % share)

can now be expressed once and behave proportionally on every model:

{ "agents": { "defaults": { "compaction": { "reserveTokensFloorShare": 0.16 } } } }

— Opus 32 K resolves the floor to floor(0.16 * 32 000) = 5 120, Sonnet 200 K to 32 000. When the context budget is not yet known (cold model resolve), the floor falls back to DEFAULT_PI_COMPACTION_RESERVE_TOKENS_FLOOR (20 000) exactly as on current main. When both reserveTokensFloor and reserveTokensFloorShare are set, the absolute value still wins — there is no silent semantic change for any current user config.

What was not tested: I did not run pnpm test src/agents/pi-settings.test.ts src/config/config.compaction-settings.test.ts src/config/zod-schema.agent-defaults.test.ts src/auto-reply/reply/agent-runner-memory.test.ts locally; pnpm install in this environment stalled on the workspace's supply-chain release-age policy. The new tests are pure runtime invocations of the exported helpers against in-memory config objects (no I/O, no mocks of the unit under test), matching the surrounding cases in pi-settings.test.ts. CI's checks-node-core-fast lane is the source of truth. I also did not regenerate config schema/docs artifacts or update docs/gateway/config-agents.md; the new fields are strictly additive so the existing operator docs remain accurate for absolute-token configs, and the bot's review notes that the docs/metadata shape is a maintainer call worth settling on the PR rather than guessing at upfront. Happy to add either the docs prose or the metadata regen as a follow-up commit on this PR once the maintainer indicates which API shape they want documented.

Strictly out of scope (per clawsweeper's review):

• No percent-string overloading of the existing numeric fields. Adding "10%" as a value type for reserveTokens would mutate an in-use config contract and the bot flagged it as the riskier of the two API shapes.
• No follow-on changes to the memory-preflight path in auto-reply/reply/agent-runner-memory.ts:511. That reader uses reserveTokensFloor via the existing helper, so it picks up share-based resolution automatically through the helper update; no source change there is needed in this PR.

Checklist

• Byte-identical behaviour for configs that do not set any of the new *Share fields. The existing absolute-token tests in pi-settings.test.ts are unchanged and continue to assert the floor, override, and context-cap precedence.
• Strictly additive Zod schema — three optional fields on the existing strict object, no rename / no widening of existing field types. Configs that omit the new fields validate identically.
• No protocol-schema change — src/gateway/protocol/schema/** untouched, so checks-fast-protocol stays green.
• No CHANGELOG.md entry (per AGENTS.md: contributors do not edit it; maintainer adds at landing).
• Targets main.