feat(agents): add context-window-relative compaction budget shares

adone0 · adone0 · commit 9ab9b50ed1ba · 2026-05-12T17:29:40.000-04:00
`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 (#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, never silently returning zero. Wire the new resolver into the two existing readers in `pi-settings.ts` (`resolveCompactionReserveTokensFloor`, `applyPiCompactionSettingsFromConfig`), both of which already accept a `contextTokenBudget` parameter. The Zod schema gains matching `.gt(0).max(1)` validators so invalid shares fail fast at config load. Tests in `pi-settings.test.ts` cover four cases for each share field: (a) the share resolves correctly when context is known; (b) the absolute sibling wins when both are set; (c) the share is ignored (default behaviour) when the runtime has no context budget; (d) positive-integer constraints on `keepRecentTokens` are preserved. Strictly out of scope (per clawsweeper's review on the issue): no percent-string overloading of the existing numeric fields, no doc regeneration in this PR, no follow-on changes to the memory-preflight path in `agent-runner-memory.ts` — those need a maintainer call on the final docs/metadata shape and are easy follow-ups once the additive share-field contract lands. Refs #72790.
diff --git a/src/agents/pi-settings.test.ts b/src/agents/pi-settings.test.ts
@@ -329,6 +329,90 @@ describe("applyPiCompactionSettingsFromConfig", () => {
 
     expect(result.compaction.reserveTokens).toBe(DEFAULT_PI_COMPACTION_RESERVE_TOKENS_FLOOR);
   });
+
+  it("resolves reserveTokensShare against the active context budget (#72790)", () => {
+    const settingsManager = {
+      getCompactionReserveTokens: () => 4_000,
+      getCompactionKeepRecentTokens: () => 8_000,
+      applyOverrides: vi.fn(),
+    };
+    // 10% of a 200 000-token context = 20 000.
+    const cfg = {
+      agents: { defaults: { compaction: { reserveTokensShare: 0.1 } } },
+    } as const;
+
+    const result = applyPiCompactionSettingsFromConfig({
+      settingsManager,
+      cfg,
+      contextTokenBudget: 200_000,
+    });
+
+    expect(result.compaction.reserveTokens).toBe(20_000);
+  });
+
+  it("absolute reserveTokens wins over reserveTokensShare when both are set (#72790)", () => {
+    const settingsManager = {
+      getCompactionReserveTokens: () => 4_000,
+      getCompactionKeepRecentTokens: () => 8_000,
+      applyOverrides: vi.fn(),
+    };
+    const cfg = {
+      agents: {
+        defaults: {
+          compaction: { reserveTokens: 7_500, reserveTokensShare: 0.1 },
+        },
+      },
+    } as const;
+
+    const result = applyPiCompactionSettingsFromConfig({
+      settingsManager,
+      cfg,
+      contextTokenBudget: 200_000,
+    });
+
+    // Absolute 7 500 wins over share-derived 20 000; the floor of 20 000
+    // still applies and bumps the actual override up.
+    expect(result.compaction.reserveTokens).toBeGreaterThanOrEqual(
+      DEFAULT_PI_COMPACTION_RESERVE_TOKENS_FLOOR,
+    );
+  });
+
+  it("ignores reserveTokensShare when contextTokenBudget is unknown (#72790)", () => {
+    const settingsManager = {
+      getCompactionReserveTokens: () => 4_000,
+      getCompactionKeepRecentTokens: () => 8_000,
+      applyOverrides: vi.fn(),
+    };
+    const cfg = {
+      agents: { defaults: { compaction: { reserveTokensShare: 0.5 } } },
+    } as const;
+
+    const result = applyPiCompactionSettingsFromConfig({ settingsManager, cfg });
+
+    // Share cannot be resolved without a context budget, so the floor
+    // default takes effect instead.
+    expect(result.compaction.reserveTokens).toBe(DEFAULT_PI_COMPACTION_RESERVE_TOKENS_FLOOR);
+  });
+
+  it("resolves keepRecentTokensShare and respects positive-int constraint (#72790)", () => {
+    const settingsManager = {
+      getCompactionReserveTokens: () => 30_000,
+      getCompactionKeepRecentTokens: () => 8_000,
+      applyOverrides: vi.fn(),
+    };
+    const cfg = {
+      agents: { defaults: { compaction: { keepRecentTokensShare: 0.15 } } },
+    } as const;
+
+    const result = applyPiCompactionSettingsFromConfig({
+      settingsManager,
+      cfg,
+      contextTokenBudget: 200_000,
+    });
+
+    // 15% of 200 000 = 30 000 keepRecentTokens.
+    expect(result.compaction.keepRecentTokens).toBe(30_000);
+  });
 });
 
 describe("resolveCompactionReserveTokensFloor", () => {
@@ -348,6 +432,40 @@ describe("resolveCompactionReserveTokensFloor", () => {
       }),
     ).toBe(0);
   });
+
+  it("resolves reserveTokensFloorShare against the active context budget (#72790)", () => {
+    expect(
+      resolveCompactionReserveTokensFloor(
+        {
+          agents: { defaults: { compaction: { reserveTokensFloorShare: 0.1 } } },
+        },
+        200_000,
+      ),
+    ).toBe(20_000);
+  });
+
+  it("absolute reserveTokensFloor wins over reserveTokensFloorShare (#72790)", () => {
+    expect(
+      resolveCompactionReserveTokensFloor(
+        {
+          agents: {
+            defaults: {
+              compaction: { reserveTokensFloor: 15_000, reserveTokensFloorShare: 0.1 },
+            },
+          },
+        },
+        200_000,
+      ),
+    ).toBe(15_000);
+  });
+
+  it("falls back to the default when reserveTokensFloorShare is set but context budget is unknown (#72790)", () => {
+    expect(
+      resolveCompactionReserveTokensFloor({
+        agents: { defaults: { compaction: { reserveTokensFloorShare: 0.1 } } },
+      }),
+    ).toBe(DEFAULT_PI_COMPACTION_RESERVE_TOKENS_FLOOR);
+  });
 });
 describe("resolveEffectiveCompactionMode", () => {
   it("defaults to default compaction mode", () => {
diff --git a/src/agents/pi-settings.ts b/src/agents/pi-settings.ts
@@ -43,11 +43,48 @@ export function ensurePiCompactionReserveTokens(params: {
   return { didOverride: true, reserveTokens: minReserveTokens };
 }
 
-export function resolveCompactionReserveTokensFloor(cfg?: OpenClawConfig): number {
-  const raw = cfg?.agents?.defaults?.compaction?.reserveTokensFloor;
+/**
+ * Resolve a context-window-relative share (in (0, 1]) into an absolute token
+ * count. Returns undefined when the share is not configured or when the
+ * caller did not supply a context budget. Always rounds down so the resolved
+ * value never exceeds `floor(share * contextTokenBudget)`. See #72790.
+ */
+export function resolveCompactionShareTokens(
+  share: unknown,
+  contextTokenBudget: number | undefined,
+): number | undefined {
+  if (
+    typeof share !== "number" ||
+    !Number.isFinite(share) ||
+    share <= 0 ||
+    share > 1 ||
+    typeof contextTokenBudget !== "number" ||
+    !Number.isFinite(contextTokenBudget) ||
+    contextTokenBudget <= 0
+  ) {
+    return undefined;
+  }
+  return Math.max(0, Math.floor(share * contextTokenBudget));
+}
+
+export function resolveCompactionReserveTokensFloor(
+  cfg?: OpenClawConfig,
+  contextTokenBudget?: number,
+): number {
+  const compactionCfg = cfg?.agents?.defaults?.compaction;
+  const raw = compactionCfg?.reserveTokensFloor;
   if (typeof raw === "number" && Number.isFinite(raw) && raw >= 0) {
     return Math.floor(raw);
   }
+  // Fall through to the share-based variant only when the absolute is
+  // unset, so the existing absolute-wins precedence is preserved.
+  const fromShare = resolveCompactionShareTokens(
+    compactionCfg?.reserveTokensFloorShare,
+    contextTokenBudget,
+  );
+  if (fromShare !== undefined) {
+    return fromShare;
+  }
   return DEFAULT_PI_COMPACTION_RESERVE_TOKENS_FLOOR;
 }
 
@@ -78,9 +115,25 @@ export function applyPiCompactionSettingsFromConfig(params: {
   const currentKeepRecentTokens = params.settingsManager.getCompactionKeepRecentTokens();
   const compactionCfg = params.cfg?.agents?.defaults?.compaction;
 
-  const configuredReserveTokens = toNonNegativeInt(compactionCfg?.reserveTokens);
-  const configuredKeepRecentTokens = toPositiveInt(compactionCfg?.keepRecentTokens);
-  let reserveTokensFloor = resolveCompactionReserveTokensFloor(params.cfg);
+  // Absolute config wins; share-based is consulted only when the absolute
+  // sibling field is unset. Both happen *before* the floor cap so the share
+  // resolves against the user's intended context budget. See #72790.
+  const reserveTokensFromShare = resolveCompactionShareTokens(
+    compactionCfg?.reserveTokensShare,
+    params.contextTokenBudget,
+  );
+  const keepRecentTokensFromShare = resolveCompactionShareTokens(
+    compactionCfg?.keepRecentTokensShare,
+    params.contextTokenBudget,
+  );
+  const configuredReserveTokens =
+    toNonNegativeInt(compactionCfg?.reserveTokens) ?? reserveTokensFromShare;
+  const configuredKeepRecentTokens =
+    toPositiveInt(compactionCfg?.keepRecentTokens) ??
+    (keepRecentTokensFromShare && keepRecentTokensFromShare > 0
+      ? keepRecentTokensFromShare
+      : undefined);
+  let reserveTokensFloor = resolveCompactionReserveTokensFloor(params.cfg, params.contextTokenBudget);
 
   // Cap the floor to a safe fraction of the context window so that
   // small-context models (e.g. Ollama with 16 K tokens) are not starved of
diff --git a/src/config/types.agent-defaults.ts b/src/config/types.agent-defaults.ts
@@ -490,6 +490,27 @@ export type AgentCompactionConfig = {
   keepRecentTokens?: number;
   /** Minimum reserve tokens enforced for Pi compaction (0 disables the floor). */
   reserveTokensFloor?: number;
+  /**
+   * Context-window-relative variant of `reserveTokens`. Resolved at runtime
+   * against the active model's context budget when known, and ignored when
+   * the absolute `reserveTokens` is also set. Value must be in (0, 1].
+   * See #72790.
+   */
+  reserveTokensShare?: number;
+  /**
+   * Context-window-relative variant of `keepRecentTokens`. Resolved at
+   * runtime against the active model's context budget when known, and
+   * ignored when the absolute `keepRecentTokens` is also set. Value must
+   * be in (0, 1]. See #72790.
+   */
+  keepRecentTokensShare?: number;
+  /**
+   * Context-window-relative variant of `reserveTokensFloor`. Resolved at
+   * runtime against the active model's context budget when known, and
+   * ignored when the absolute `reserveTokensFloor` is also set. Value
+   * must be in (0, 1]. See #72790.
+   */
+  reserveTokensFloorShare?: number;
   /** Max share of context window for history during safeguard pruning (0.1–0.9, default 0.5). */
   maxHistoryShare?: number;
   /** Additional compaction-summary instructions that can preserve language or persona continuity. */
diff --git a/src/config/zod-schema.agent-defaults.ts b/src/config/zod-schema.agent-defaults.ts
@@ -178,6 +178,12 @@ export const AgentDefaultsSchema = z
         reserveTokens: z.number().int().nonnegative().optional(),
         keepRecentTokens: z.number().int().positive().optional(),
         reserveTokensFloor: z.number().int().nonnegative().optional(),
+        // Context-window-relative variants — value in (0, 1]. Resolved
+        // against the active model's context budget at runtime; ignored
+        // when the absolute sibling field is also set. See #72790.
+        reserveTokensShare: z.number().gt(0).max(1).optional(),
+        keepRecentTokensShare: z.number().gt(0).max(1).optional(),
+        reserveTokensFloorShare: z.number().gt(0).max(1).optional(),
         maxHistoryShare: z.number().min(0.1).max(0.9).optional(),
         customInstructions: z.string().optional(),
         identifierPolicy: z
