feat(session): add ratio-based auto-commit threshold with model context awareness

[mvanhorn]

Description

Add auto_commit_threshold_ratio and context_window parameters to Session.__init__, allowing the commit threshold to scale with the model's context window size. When users switch between models (1M vs 200K tokens), the threshold adapts automatically instead of requiring manual recalculation.

Also adds commitTokenThresholdRatio to the OpenClaw plugin config.

Related Issue

Fixes #1172

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Test update

Changes Made

• Add auto_commit_threshold_ratio: Optional[float] and context_window: Optional[int] params to Session.__init__ with input validation
• Add effective_commit_threshold property: computes int(context_window * ratio) when both are set, falls back to the fixed auto_commit_threshold otherwise
• Add commitTokenThresholdRatio to the OpenClaw plugin config type, schema parser, allowed keys list, and uiHints
• Add unit tests covering all threshold computation paths and validation edge cases

Priority order: ratio * context_window > fixed auto_commit_threshold > default 8000.

Testing

• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have tested this on the following platforms:
  • Linux
  • macOS
  • Windows

9 test cases cover: default threshold, fixed override, ratio with 1M model, ratio with 200K model, ratio overriding fixed value, ratio without context_window fallback, and 4 validation error cases.

Checklist

• My code follows the project's coding style
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• Any dependent changes have been merged and published

Screenshots (if applicable)

Demo

Shows the effective_commit_threshold property computing different thresholds: default 8000, 1M model at 38% = 380K, 200K model at 38% = 76K, and ratio overriding a fixed value.

Additional Notes

The Session class stores auto_commit_threshold but the actual commit decision is made by the caller (OpenClaw plugin or bot). This PR adds the ratio computation on both sides: Python Session.effective_commit_threshold for callers using the Python API directly, and commitTokenThresholdRatio in the TS plugin config for OpenClaw users. The existing commitTokenThreshold / auto_commit_threshold parameters remain unchanged for backward compatibility.

This contribution was developed with AI assistance (Claude Code).

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis 🔶 1172 - Partially compliant Compliant requirements: Added commitTokenThresholdRatio config option (TypeScript and Python) Implemented ratio-based threshold calculation Set priority: ratio * context_window > fixed threshold > default Added validation for ratio (0 < ratio < 1) and context_window (>0) Added tests for the new feature Non-compliant requirements: Ratio-based threshold not integrated into actual commit logic (effective_commit_threshold property not used) TypeScript config uses 0 as sentinel for unset ratio, which Python rejects Requires further human verification: Integration with OpenClaw gateway to read model context window

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🏅 Score: 70

🧪 PR contains tests

🔒 No security concerns identified

✅ No TODO sections

🔀 No multiple PR themes

⚡ Recommended focus areas for review Configuration Mismatch TypeScript config uses 0 as a sentinel for unset commitTokenThresholdRatio, but Python rejects 0 (requires 0 < ratio < 1). This will cause errors for users who don't explicitly set the ratio. commitTokenThresholdRatio: (() => { const raw = toNumber(cfg.commitTokenThresholdRatio, 0); if (raw > 0 && raw < 1) return raw; if (raw !== 0) { throw new Error("commitTokenThresholdRatio must be between 0 and 1 (exclusive)"); } return 0; })(), Unused Feature The effective_commit_threshold property is defined but not used in the session's commit logic. The ratio-based threshold will not take effect until this property is integrated into the token threshold check. @property def effective_commit_threshold(self) -> int: """Compute the effective auto-commit threshold. Priority: ratio * context_window > fixed value > default (8000). When auto_commit_threshold_ratio and context_window are both set, the threshold is computed as a percentage of the model's context window. """ if self._auto_commit_threshold_ratio is not None and self._context_window is not None: return int(self._context_window * self._auto_commit_threshold_ratio) return self._auto_commit_threshold

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Fix default ratio value in TS config The current code returns 0 as the default for commitTokenThresholdRatio, which is invalid in the Python backend (raises ValueError). Instead, return undefined when the field is not explicitly set, so the Python backend uses its default None value. Also properly validate explicit 0 values as invalid. examples/openclaw-plugin/config.ts [239-246] commitTokenThresholdRatio: (() => { - const raw = toNumber(cfg.commitTokenThresholdRatio, 0); + if (cfg.commitTokenThresholdRatio === undefined) { + return undefined; + } + const raw = toNumber(cfg.commitTokenThresholdRatio, NaN); if (raw > 0 && raw < 1) return raw; - if (raw !== 0) { - throw new Error("commitTokenThresholdRatio must be between 0 and 1 (exclusive)"); - } - return 0; + throw new Error("commitTokenThresholdRatio must be between 0 and 1 (exclusive)"); })(), Suggestion importance[1-10]: 8 __ Why: The original TypeScript config returned 0 as the default for commitTokenThresholdRatio, which is invalid in the Python backend (raises ValueError). The fix returns undefined when the field isn't set (mapping to Python's None), and properly validates explicit invalid values, preventing backend errors.	Medium