Introduction¶

As DSH sessions run for a long time, historical prefixes inflate the token count for every request. Native Basic compaction is responsible for keeping the system alive, but it doesn’t care whether this compaction actually used the cache, nor does it care about the cache cost for this model. lloydzhou/dsh-smart-compaction targets this gap: it separates compaction execution from the “economic strategy.” Execution prioritizes the cache, while the strategy layer defaults to observation only, leaving decision-making to the user.

It belongs to the “Model Inference” category, maintained by lloydzhou. Below is an introduction to what this plugin does, how to install it, and how to confirm it is actually running.

What is it¶

In one sentence: a publishable npm package, a DSH plugin entry point, internally separating compaction execution and adaptive economic strategy. It does not require installing a separate strategy package and does not modify the DSH host.

It explicitly does not do three things: it does not guarantee cache hits, it does not guarantee the globally lowest cost, and it does not fake the model’s currency price field.

The plugin version follows DSH’s three-part version line (0.2.1), with independent RC number increments. The installation example in the README is written as 0.2.1-rc.1, and the version field in the repository’s package.json is currently 0.2.1-rc.3; the host compatibility range is declared separately in engines.dsh as >=0.2.1-rc.3. The version descriptions in the README and package.json are not entirely consistent. When installing in practice, use the RC number you want to install, and verify it against the target host’s compatibility range.

Core Features¶

Cache-First Compaction¶

The engine uses cacheFirst (enabled by default) as a switch. When enabled, summary requests try to reuse existing cached suffixes; when disabled, it falls back to the native BasicCompactionEngine, and the adaptive strategy becomes inactive.

Summary Parameter Continuity¶

Under the same session, provider, and model, if the native summary request does not explicitly provide reasoningEffort, the plugin fills it in from the last routed request header. It does not inherit across different routes, and it does not overwrite existing parameters. It only fixes parameter continuity; it does not prove that effort affects caching. See DSH #11816 for related discussion.

Adaptive Economic Strategy¶

adaptive.mode takes off / observe (default) / active. The strategy is read for every decision; no restart is needed after changing it.

The public model metadata for RC.3 / RC.5 does not have a currency price field, so the plugin will not pretend to read it. By default, when the price is missing, it uses the official peak-hour USD reference price for DeepSeek V4.1 Flash, and marks the source, date, and reference model in the pricing field of the strategy log. This is not the real bill for the current route. referencePriceFallback: false can disable this fallback; when the price is missing or the currency is incompatible, it returns missing-prices, but fixed strategies and hard pressure protection remain effective. observe never applies economic suggestions.

Structured Logs¶

When cacheFirst is enabled (regardless of whether adaptive is on/off), the backend outputs cache-first-compaction/operation and cache-first-compaction/result at the info level. Fields include sessionId, unique operationId, trigger, status, surfaceChanged, and a persistent compactionId for each summary attempt. It does not write chat context, nor does it record prompts, summary text, tool outputs, or raw error messages.

A few points prone to misinterpretation:

1. summaryAttempts is the count of times the stock summarize hook is actually entered, including retries, failures, and cancellations; it does not equal the number of model calls.
2. llmStreamCalls / calls[] record the actually observed public llm/stream calls, with the evidence field distinguishing the source. You cannot treat stream calls directly as billed requests—the public waterfall triggers before the adapter lookup, preparation, and actual dispatch; only when pruning/no summary is used are modelCalls: 0 and providerDispatch: none seen.
3. usage.inputTokens is uncached input. The three types of input counts in DSH are mutually exclusive; for complete counting, promptTokens = inputTokens + cacheReadTokens + cacheWriteTokens. Missing counts are recorded as null instead of 0, and calls that fail and do not report usage are not treated as zero consumption.
4. knownUsageTotals only aggregates reported fields, not the complete total cost.

By default when adaptive.mode: observe, after there is a request header, structured info logs adaptive-compaction/decision are recorded during automatic pressure checks. These logs are found in the DSH process logs or log exporters running that session, not in chat messages; the specific path is determined by the host configuration.

Chat UI Compression Card¶

The external client bundle reuses the compaction and manual-compaction rendering slots of the public conversation.chat.node, preserving the summary and original estimated quantities. When collapsed, it is a single line, appending the observed summary stream call count and cache ratio after the original text. When expanded, it shows the decision and execution details first, then the original summary. Diagnosis uses experimental ignorable plugin records, does not enter the model context, and keeps at most the last 64 meaningful operations. The README states that visual effects have not yet been verified in a running GUI; you need to update the client and refresh to confirm.

Installation and Enablement¶

Installation commands after publishing to npm (installing the same package in both web and desktop profiles):

dsh plugin --profile web add dsh-smart-compaction@0.2.1-rc.1
dsh plugin --profile desktop add dsh-smart-compaction@0.2.1-rc.1

For local development, use pnpm link. Note that linked packages do not resolve peers from the target node_modules according to normal rules; this is a general reminder for link mode, not a sign of DSH resolution failure. After the build artifacts are packaged into a tarball, the operator must explicitly execute:

npm ci
npm run build
npm run typecheck
npm test
npm pack
dsh plugin --profile web add ./dsh-smart-compaction-0.2.1-rc.1.tgz

Environment requirements: Node.js >=24.9.0, verified hosts are DSH 0.2.1-rc.3 and 0.2.1-rc.5, Cordis 4.0.5, Schemastery 3.18.5. The README also notes “not yet published to npm,” indicating that the commands above represent the state after the publishing process has been carried out.

Enable and Disable¶

RC.3 / RC.5 will retain the old engine version for running Agents, and the public interface does not support switching engines directly for non-empty sessions. You must restart Web after switching, then restore the original session; no need to create a new one or change history. Do not restart in the middle of an ongoing compaction.

• Enable bundle or main switch: The startup adapter derives the plugin engine from the current standard configuration.
• Disable the main entry smart-compaction-integration: Retain the bundle’s startup adapter, and register the unconverted native standard on the next startup; the old smart-compaction alias also points to the native configuration.
• Disable the entire bundle: Undo the layered patch, restoring the original host standard declaration.

The frontend uses a public priority of -10 to override the native priority of 0, preserving the native registration. smart-compaction-preset-adapter is just the bundle’s startup connection component, not a second functional switch; do not disable it separately.

Settings Form¶

The plugin details page (Plugins → Smart Compaction) has two settings that write immediately to the current profile, corresponding to the volatile fields of the root entry smart-compaction-integration: cacheFirst (enabled by default) and adaptiveMode (off / observe (default) / active). The form requires the root entry id in the profile to be smart-compaction-integration.

Behavior of the two switch combinations:

Typical Usage¶

After installing and restarting the host, existing standard sessions will use dynamically derived compression configurations; no need to open a new session. The plugin page showing agent-preset / Running only indicates that the preset has been registered; it does not prove that the current session is actually using this engine, which must be confirmed via logs.

Confirming an actual run:

1. Open the host info-level logs.
2. Trigger an automatic pressure check or manual /compact.
3. Find cache-first-compaction/operation and cache-first-compaction/result in the host process logs.
4. When the actual summary succeeds, the host logs contain compaction (step pressure): shadowed ... or overflow recovery; the session persistent logs contain compaction/start, compaction/summary, replacement messages, and compaction/end. compaction/prune is only used for tool pruning; summary records will not appear out of thin air.

Note that decisionApplied: true only indicates that the active strategy returned a decision; it does not prove that compaction has occurred, nor does it represent saving money. off does not generate strategy logs, and no strategy check is performed when there is no header. The backend strategy logs carry sessionId / operationId, which can be matched with the execution logs.

Scenarios and Notes¶

Suitable for DSH developers already using standard presets who want to understand whether compression is actually using the cache. To observe before deciding, use the default cacheFirst: true + adaptiveMode: observe; to use a fixed cache-first strategy, set off; to actually integrate bounded economic suggestions into decisions, set active. Non-standard custom presets still need to be explicitly integrated; the plugin will not forcibly hijack other compression implementations.

Points to note:

1. The plugin runs with the current DSH process permissions; you should check the source code and license before installing (the repository declares MIT).
2. During installation, version conflicts with other plugins in that profile may be reported. Handle this based on the package name in the warning: exact version/scope conflicts for old browser/computer-use, sub-agents, or usage-stats are not part of this plugin. Prioritize upgrading or disabling incompatible plugins; granting version exemptions directly is not recommended.
3. The host runtime libraries are declared as peerDependencies. For linked installation, the host resolver must share these libraries; otherwise, two copies of Session may appear, causing class identity validation failure for public plugin record functions. Diagnostic failures will output a warning without sensitive content.
4. client.inject declares the host-provided UI/locale service dependency, used only to enhance compression display, not another compression engine. The actual interface start/stop for Desktop has not been separately end-to-end verified.
5. Do not use npm install as an activation method—it only installs files, it does not activate the Cordis bundle.

Conclusion¶

The actual value of this plugin lies in separating “whether compression uses the cache” and “how much the cache costs,” and providing a default path for observation, rather than stuffing economic decisions into the execution pipeline right from the start. To further verify installation and version details, see the directory page and the repository:

• Directory page: https://www.skillhub.cn/plugins/lloydzhou/dsh-smart-compaction
• GitHub: https://github.com/lloydzhou/dsh-smart-compaction