Introduction¶

When manually configuring third-party gateways in DSH, model IDs (for example, grok-4.6) usually do not match the built-in pi-ai catalog (for example, x-ai/grok-4.6). This causes context window resolution to fall back to the default value defaultContextWindow (262144). At the same time, the compaction backend only accepts ratio format, making it difficult to directly set absolute thresholds.

The dsh-context-budget plugin solves these two problems: it adds configuration groups for context window, compaction threshold, and retain budget to each pi-ai provider card, and adds reasoning effort control in the bottom-right corner of the editor.

Installation and Enablement¶

Run the following command to install the plugin:

dsh plugin --profile web add dsh-context-budget

After installation is complete, restart dsh web, go to the Settings → Models page, and expand any pi-ai provider card to see the new “Context budget” group.

Core Features¶

Context Window and Compaction Threshold¶

The plugin converts parameters that are difficult to set directly into intuitive values:

The threshold is stored as a ratio, so if the context window size is modified later, click Apply again to recalculate the ratio.

Reasoning Effort Control¶

The plugin adds a reasoning effort selector in the bottom-right corner of the editor (next to the model selector). It reads the current session’s model and tries to obtain the levels declared for that model from the catalog; if not present, it identifies the provider based on the model ID and uses its profile.

The supported providers and levels are as follows:

After selection, the plugin writes the level to the reasoningEfforts field for the corresponding model in settings.yaml. If the gateway’s interface field spelling differs from the standard, manually edit the value in settings.yaml.

Configuration Details and Validation¶

Write Mechanism¶

The plugin makes changes through cordis.patch.yml and only modifies marked managed blocks. Before writing, it backs up the original file as cordis.patch.yml.contextbudget.bak, validates each provider/model rule on disk, and rolls back immediately if validation fails.

Validation Rules¶

Before saving, the plugin validates the configuration and refuses to write in cases including:
* The context window and threshold must be positive integers;
* The threshold must be less than the context window;
* The derived ratio must be greater than 0.16 (the backend default retention ratio) and less than 1;
* The retain budget must be less than the threshold;
* The route must contain at least one model ID.

Why Not Replace the Compaction Engine¶

The compaction-basic engine re-resolves the context window at each step via llm.resolveModelInfo() and computes floor(contextWindow × thresholdRatio). Therefore, providing just two numbers (the window and the ratio) is enough because the engine already has all the functionality it needs; the plugin does not need to replace the engine.

Limitations and Notes¶

• Scope: Applies only to pi-ai routes.
• Default value fallback: defaultContextWindow is a fallback value and does not override model entries already defined in the catalog or the model’s own context window.
• Max tokens: The maxTokens field is not controlled by this plugin and is fixed at 32768.
• Cost: Compaction triggers additional summarization requests; the lower the threshold, the more requests are made.
• Uninstall limitation: Uninstalling the plugin does not remove persisted configuration already written (such as defaultContextWindow and settings in cordis.patch.yml); manual removal is required.

Uninstall¶

dsh plugin --profile web remove dsh-context-budget

After uninstalling, the persisted configuration remains. To restore the default state, manually delete the defaultContextWindow field in the llm-pi-ai settings and the block marked with # dsh-context-budget managed block in cordis.patch.yml.