dsh-compaction-policy

dsh-compaction-policy

中文 · Development & host tests · Security

An experimental global compaction policy for DeepSeek Harness. Keep the official Basic summarizer, checkpoint records, tool pairing, token meter, UI event protocol, native /compact, and overflow recovery. Change proactive budgeting, range selection, and no-progress retries—without selecting a special preset.

Experimental v0.2.2. The bundle load-admits the DSH ^0.2.1-rc.1 host line (0.2.x, including later release candidates) and Cordis 4.0.x; the policy then activates only when five Basic method fingerprints match the verified implementation. A host bump that changes only version labels needs no plugin update, and an unrecognized host build leaves the plugin loaded but inert on stock Basic instead of failing startup. Actual-host tests with synthetic sessions and scripted model responses have passed. This is not proof of live GUI behavior or summary quality on a native Windows/real-model session. No lossless-summary or larger-context-window claim is made.

What installation changes

The default bundle installs exactly one root plugin:

- id: compaction-policy-global
  name: dsh-compaction-policy/global
  config: {}

• Global policy: covers eligible existing and future official Basic instances in the same Cordis runtime, including ordinary presets. It uses Basic's native pressure mechanism, adds no compaction engine or automatic compaction listener, and does not switch presets.
• No special preset: the package registers no preset and does not filter the preset registry. Continue using your normal presets.
• Your current default provider and preset stay unchanged. Main-request output limits, reasoning effort, provider/model selection, and token accounting are not rewritten.

Only the fingerprint-verified official Basic implementation is targeted. Custom backends, subclasses, and instances with method overrides are skipped. Presets with no compaction, including minimal compositions without it, are unaffected. “Global” does not mean every DSH process or profile on the machine.

Default policy: 90%, with no double deduction

Stock Basic can trigger early when a model permits a large output:

stock threshold = floor(min(W × 0.8, W − requestMaxTokens − 65536))

reservedOutput  = min(requestMaxTokens, outputReserveCap)
policy threshold = floor(min(W × thresholdRatio,
                             W − reservedOutput − headroomTokens))
retentionTarget = floor((W − reservedOutput) × retainRatio)

Defaults are thresholdRatio: 0.9, outputReserveCap: 0, headroomTokens: 0, so the proactive threshold is exactly floor(W × 0.9). The remaining 10% is the margin; it is not deducted a second time. For a 262,144-token window with a 131,072-token output cap, the threshold changes from 65,536 to 235,929 tokens. This is arithmetic, not a performance benchmark.

pruneToolResults: false applies only to the new proactive-pressure path. That path does not pre-prune tool results; old content is summarized through Basic. It does not disable the native pruner service or change stock-mode, manual, or confirmed-overflow behavior.

An output cap is not guaranteed available space. A 90%-full prompt and a full 128K completion cannot coexist in a 256K window. The adapter/server must enforce remaining capacity; providers that validate input + max_tokens may reject earlier. Native overflow recovery still applies. This plugin is not an HTTP output-budget clamp.

Selection and failure guard

• Retain recent history with a soft target of 16%. Whole messages and tool-call/result units stay atomic; the newest unit remains verbatim even when larger than the target.
• Allow an older large message into the summary rather than repeatedly summarizing only a tiny preceding checkpoint. System nodes are protected; a later system node is a selection barrier.
• Require at least 2,048 non-checkpoint tokens in the selected range before proactive summarization.
• Make at most one summary transaction per pressure step; do not immediately summarize the fresh checkpoint again.
• Back off failures for 60s, 120s, 240s… up to 10 minutes. Expiry allows one probe on the next pressure check, not a background model call. Material candidate changes may permit earlier retry; unrelated tail appends do not.
• Preserve native manual and confirmed-overflow paths, retry limits, transaction completion, and durable-progress checks. They bypass the proactive guard.

Install

Distribution is via GitHub, not npm. Install the v0.2.2 release tag:

github:huohua-dev/dsh-compaction-policy#v0.2.2

Desktop-managed profile

Use the Desktop plugin-manager UI to add or update the GitHub source, then fully quit and restart Desktop so the existing host process is replaced. A page refresh or profile reload is not a substitute after an upgrade: an old-process import failure was observed and cleared by a full restart. Desktop-managed plugin changes via CLI are rejected; do not use a --profile desktop CLI workaround.

After loading, use your existing normal preset. No special preset selection is required. Run /compaction-policy-global status in the session to inspect coverage and the effective policy. Installation does not choose a new default provider or preset.

Non-Electron-managed web profile only

For a web profile not managed by Electron/Desktop:

dsh plugin --profile web add github:huohua-dev/dsh-compaction-policy#v0.2.2

Reload/restart that existing host. This CLI example is not an alternative installation path for Desktop.

Configure the global entry

Apply a user profile override to compaction-policy-global, with policy fields under config.policy. Row configuration is replaced as a whole, not deep-merged; restate any custom values you need to retain. Reload the profile after changing it.

For example, use stock behavior except on one exact route:

- id: compaction-policy-global
  config:
    policy:
      mode: stock
      modelPolicies:
        - provider: your-local-provider
          model: your-model-id
          mode: policy
          thresholdRatio: 0.9
          outputReserveCap: 0
          headroomTokens: 0
          pruneToolResults: false

Provider/model matching is exact and case-sensitive. Without this opt-in route example, the default policy applies to all eligible Basic instances.

Policy fields except modelPolicies and dryRun can be overridden per route. Unknown keys and invalid values are rejected. Invalid pressure budgets produce diagnostics, not an invented larger window.

Main output and summary configuration remain separate

The global entry has no basic field, including under config.policy. Each engine keeps its original Basic configuration: summary provider/model, summary output budget, reasoning behavior, automatic enablement, and stock/manual/overflow settings. Configure those at the engine's existing Basic row, not in the global plugin.

Where upstream defaults are used, the 65,536-token summary cap stays intact. Policy headroom 0 does not set the summary cap to zero. The main request's output cap and thinking settings also remain unchanged. Basic's auto: false retains its native semantics: automatic pressure and overflow listeners are off, while manual /compact remains available.

Status and recovery

/compaction-policy-global [status|reset]
/compact

status reports coverage and proactive diagnostics without transcript content. reset clears the current session's proactive retry guard; it does not compact, rewrite history, or change the model. Native /compact remains the manual compaction command. A reduction that remains over threshold is reported as compacted-still-above-threshold, not as “back under budget”. Failure state is in memory per live session, not persisted across restarts.

After a host upgrade, status is also the compatibility answer: enabled: true means the verified fingerprints still match. If a future host really changes a verified method, the plugin stays loaded, logs a warning, and reports enabled: false with reason unsupported-host while stock Basic keeps working untouched; update the plugin when a reviewed build is available. Maintainers can run npm run compat:host against the new host for the full fingerprint report (see CONTRIBUTING).

On disposal, the global policy becomes inactive first, then drains in-flight work before safe restoration. Foreign wrappers are not overwritten: if another plugin has wrapped a patched method, this plugin's wrapper stays inert until safe restoration or restart. Disabling does not forcibly rebind running agents.

Upgrade from older test builds

The old test preset compaction-policy is no longer registered. There is no old-session restoration compatibility; previous test sessions are not a supported upgrade target. The package does not delete or rewrite session logs.

1. Remove obsolete user profile overrides for compaction-policy-legacy and compaction-policy-preset, plus custom references to those removed entries. Package installation does not silently edit your profile.
2. If your default still points to the test preset, explicitly restore an existing normal preset as the default.
3. Update through the Desktop plugin-manager UI, then fully quit and restart Desktop. For a non-Electron-managed web profile, update through its plugin manager and restart that host. Check a new chat with a normal preset and /compaction-policy-global status.

Custom compositions

The root dsh-compaction-policy backend and dsh-compaction-policy/global entry remain available; the /preset and /legacy exports are removed. The default bundle loads only the global entry. Custom compositions must use only one backend inside their isolated compaction group; the global plugin is not a replacement backend. Headless use of the global entry requires the host's commands and agentPresets services; a composition without them cannot load it unchanged.

Disable or uninstall

• To stop the global policy, disable compaction-policy-global; alternatively set config.policy.mode: stock and remove any route overrides that still enable policy mode.
• For full removal, finish/stop affected work, remove your own plugin overrides and custom-composition references, and ensure the default is an existing normal preset.
• Desktop: remove the bundle through the Desktop plugin-manager UI, then fully quit and restart Desktop.
• Non-Electron-managed web only: dsh plugin --profile web remove dsh-compaction-policy, then restart that host.
• After removal, open a new chat with a normal preset and verify that it loads and uses the host's normal compaction behavior.

Uninstalling does not delete or rewrite session logs, migrate test-preset identities, or restore all pre-compaction history into active context.

Limits and verification

Summary quality and provider capacity remain model/upstream concerns. Meter values are host estimates; the plugin does not falsify token counts, lower main-request reasoning, add a compression service, wrap global fetch, patch ASAR, or ship another DSH kernel. Host plugins run with host privileges; model tool approvals do not sandbox them.

Compatibility has two separate layers. The declared DSH range only decides whether the bundle may load, so release-candidate and patch bumps inside the 0.2.x host line no longer need a plugin re-pin. The five-method fingerprints decide whether the policy may activate: they are a deliberate safety gate, not a promise that changed upstream internals are supported. If a fingerprint ever differs, the policy fails safe to stock behavior and the new seam must be re-read and re-tested before the fingerprint is refreshed—never merely widened or re-recorded blind. Actual-host synthetic tests do not establish live UI or native Windows summary quality.

npm test
npm run check
npm run pack:check

See development and host-test instructions for the synthetic real-host suite. These checks do not constitute a live-model acceptance test.

License and inspiration

MIT © 2026 huohua-dev. See NOTICE for upstream contracts and related work. No third-party plugin implementation or DSH kernel is vendored.