dsh-local-models 0.3.0 → 0.3.1

package/lib/index.js

@@ -89,11 +89,22 @@ const MMPROJ_CPU = process.env.LOCAL_MODELS_MMPROJ_CPU !== "0";
  * the advertised maxTokens becomes the adapter's defaultMaxTokens, which
  * dsh-compaction-basic uses as its reserved output `O` in `W - O - headroom`.
  * Advertising the whole window (the old 131K) leaves no message budget at
- * `W = O` — proactive compaction warns once and never fires. Half-window
- * cap keeps at least half the context for history so headroom tuning can
- * always make compaction viable. Heavy xhigh thinking that needs more must
- * raise per-request maxTokens explicitly (which honestly moves the
- * compaction threshold earlier instead of silently disabling it).
+ * `W = O` — proactive compaction warns once and never fires.
+ *
+ * NOTE — the 32K cap alone does NOT buy a late threshold under the core
+ * defaults (headroomTokens 65536, thresholdRatio 0.8, retainRatio 0.16; see
+ * compactionBudgetFor() below). For a 131072 window with O = 32768 the
+ * effective threshold is min(0.8 * W, W - O - headroom) = 32768, i.e. the
+ * session starts compacting at ~32-38K pressure tokens (the meter prices
+ * tools + system on top of the surface, so the visible trigger lands a few K
+ * above the raw threshold) — and with xhigh + preserveThinking every turn
+ * adds 10-20K thinking tokens, so compaction fires again on the next step:
+ * the "compaction loop". The honest fix for mid-size windows is a per-model
+ * headroom override in the dsh profile (headroom ~6-16K moves the 131K
+ * threshold to ~82-92K), not a smaller O — shrinking O truncates the xhigh
+ * thinking blocks this cap exists to protect. Heavy xhigh thinking that
+ * needs more must raise per-request maxTokens explicitly (which honestly
+ * moves the compaction threshold earlier instead of silently disabling it).
  */
 const MAX_OUTPUT_TOKENS = 32768;
 /** Default output share of the window: never offer more than half as max
@@ -101,6 +112,71 @@ const MAX_OUTPUT_TOKENS = 32768;
 function defaultMaxOutput(contextWindow) {
 	return Math.max(1, Math.min(MAX_OUTPUT_TOKENS, Math.floor(contextWindow / 2)));
 }
+/**
+ * dsh-compaction-basic defaults this plugin's advertisement is priced
+ * against. Duplicated here (not imported) because the core package is not a
+ * dependency of this plugin — keep in sync with upstream's resolveConfig().
+ */
+export const COMPACTION_DEFAULTS = {
+	thresholdRatio: 0.8,
+	headroomTokens: 65536,
+	retainRatio: 0.16,
+};
+/**
+ * Price one advertised window the way dsh-compaction-basic's
+ * resolveCompactSpec() does, so the tab/skill can tell the user WHEN
+ * proactive compaction will actually fire — before they hit the loop.
+ *
+ *   messageBudget = W - O            (history available to messages)
+ *   pressure      = messageBudget - headroom
+ *   threshold     = min(floor(W * ratio), pressure)   (fire at/above this)
+ *   retain        = floor(messageBudget * retainRatio) (tail kept per compact)
+ *
+ * `viable` is false when the pressure budget is <= 0: proactive compaction
+ * is then disabled entirely (core warns once and only recovers on overflow).
+ * That is the 96K-window cliff: W = 98304, O = 32768 leaves exactly 0.
+ *
+ * `recommendedHeadroom` is the headroom override that lands the threshold at
+ * ~70% of the window (clamped to [4096, 65536] so a summary + one retry
+ * always fit): the value to put in a `modelPolicies` entry for this route.
+ * Pure; `maxTokens` defaults to what buildProviderProfile would advertise.
+ */
+export function compactionBudgetFor(contextWindow, opts = {}) {
+	const W = Number.isInteger(contextWindow) && contextWindow > 0 ? contextWindow : 8192;
+	const O = Number.isInteger(opts.maxTokens) && opts.maxTokens > 0
+		? opts.maxTokens
+		: defaultMaxOutput(W);
+	const ratio = typeof opts.thresholdRatio === "number" && opts.thresholdRatio > 0 && opts.thresholdRatio <= 1
+		? opts.thresholdRatio
+		: COMPACTION_DEFAULTS.thresholdRatio;
+	const headroom = Number.isInteger(opts.headroomTokens) && opts.headroomTokens >= 0
+		? opts.headroomTokens
+		: COMPACTION_DEFAULTS.headroomTokens;
+	const retainRatio = typeof opts.retainRatio === "number" && opts.retainRatio > 0 && opts.retainRatio < ratio
+		? opts.retainRatio
+		: COMPACTION_DEFAULTS.retainRatio;
+	const messageBudget = W - O;
+	const pressureBudget = messageBudget - headroom;
+	const thresholdTokens = Math.floor(Math.min(W * ratio, pressureBudget));
+	const retainTokens = Math.floor(messageBudget * retainRatio);
+	// Headroom that would put the threshold at ~70% of the window: the
+	// pressure budget must cover 0.7 * W, i.e. headroom <= message - 0.7W.
+	const recommendedHeadroom = Math.max(
+		4096,
+		Math.min(COMPACTION_DEFAULTS.headroomTokens, messageBudget - Math.floor(W * 0.7)),
+	);
+	return {
+		contextWindow: W,
+		maxTokens: O,
+		headroomTokens: headroom,
+		messageBudget,
+		pressureBudget,
+		thresholdTokens,
+		retainTokens,
+		viable: pressureBudget > 0 && retainTokens < thresholdTokens,
+		recommendedHeadroom,
+	};
+}
 /** Fixed-MTP ceiling. The tab offers 0-7 and the API clamps here: upstream
  * accepts any `--spec-draft-n-max` and clamps the effective depth to the
  * model's own nextn depth at load. Depth 3 is the measured 16 GiB sweet spot
@@ -1634,7 +1710,10 @@ export function buildProviderProfile(st, requestedRoute) {
 			// series is a heavy thinker and at xhigh its thinking block alone
 			// blows past small ceilings, so 32K is the default — but never more
 			// than half the window, or compaction's `W - O - headroom` budget
-			// collapses and proactive compaction never fires. Need more room
+			// collapses and proactive compaction never fires. NOTE: under the
+			// core defaults (headroom 65536) a 131072 window still thresholds
+			// at ~32K — see compactionBudgetFor(); mid-size windows need a
+			// per-model headroom override, not a smaller O. Need more room
 			// for a monster thinking block? Raise per-request maxTokens
 			// explicitly instead.
 			maxTokens: defaultMaxOutput(contextWindow),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-local-models",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "dsh addon: a Local Models settings tab that starts and stops a llama-server child process living with the dsh host process.",
   "type": "module",
   "main": "lib/index.js",

package/skills/dsh-local-models-ops/SKILL.md

@@ -105,6 +105,30 @@ The registered model advertises `maxTokens: min(32768, floor(ctx/2))` — a
 message budget and proactive compaction never fires. Heavy-thinking models
 at xhigh that need more than 32K must raise per-request maxTokens
 explicitly (which honestly moves the compaction threshold earlier).
+Compaction threshold under the core defaults (headroomTokens 65536,
+thresholdRatio 0.8, retainRatio 0.16) is `min(0.8*W, W - O - headroom)` —
+so a 131072 window with O = 32768 thresholds at **32768**, firing at
+~32-38K pressure tokens and looping with xhigh + preserveThinking (every
+turn re-adds 10-20K thinking tokens). A 98304 window is worse: pressure
+exactly 0, proactive compaction disabled entirely. The fix is a per-model
+headroom override in the dsh profile (needs a `dsh web` restart — loader
+normalization happens at boot), NOT a smaller O (that truncates xhigh
+thinking). Compute it with `compactionBudgetFor(ctx).recommendedHeadroom`
+(~6.5K for 131K → ~92K threshold; ~4K floor for 96K → ~61K). Example for
+the Swift 131K route (also add siblings as needed):
+
+```yaml
+- id: compaction-basic
+  name: '@deepseek-ai/dsh-compaction-basic'
+  config:
+    modelPolicies:
+      - provider: local-router
+        model: swift-1-5-qwen3-8-27b
+        headroomTokens: 6554
+```
+
+Shortcut with zero config edits: run the bigger window instead — the
+200K/250K profiles threshold at ~106K/158K under defaults.
 For opencode against the spawned server:
 - the opencode config resolves per directory (project `opencode.json` beats
   nothing; the global `~/.config/opencode/opencode.json(c)` is authoritative