@sagmans/dsh-auto-compact 0.2.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -5,17 +5,31 @@ shipped window-ratio trigger. It condenses at a fixed price on large-window
5
5
  models, while every model whose window is already smaller than that budget keeps
6
6
  its proportional trigger.
7
7
 
8
- ```
8
+ ```text
9
9
  trigger = min(thresholdTokens, floor(contextWindow x thresholdRatio))
10
10
  ```
11
11
 
12
- Releases publish to npm as [`@sagmans/dsh-auto-compact`](https://www.npmjs.com/package/@sagmans/dsh-auto-compact); every release carries a provenance attestation built by the tag workflow, and no npm token is stored. The code is [MIT licensed](LICENSE).
12
+ Releases publish to npm as
13
+ [`@sagmans/dsh-auto-compact`](https://www.npmjs.com/package/@sagmans/dsh-auto-compact);
14
+ every release carries a provenance attestation built by the tag workflow, and no
15
+ npm token is stored. The code is [MIT licensed](LICENSE).
13
16
 
14
17
  ## Requirements
15
18
 
16
- - Node.js 24 LTS (verified with 24.20.0).
19
+ - Node.js 24 LTS (verified with 24.22.1).
17
20
  - pnpm 11.21.0 for this repository.
18
- - A DeepSeek Harness install on the supported line: `>=0.1.5-rc.1 <0.3.0`, verified against `0.1.5-rc.2`, `0.1.5-rc.3`, `0.1.7-rc.2`, and `0.2.0-rc.2`. The plugin declares that range as a peer dependency, so a profile resolves the harness copy it already has rather than a second framework instance, and `dsh.compatibility.dshReleases` names the releases that passed the gates — the harness refuses an install whose peer range does not cover it.
21
+ - uv for the release-helper checks. They require a uv-managed Python and stop
22
+ if uv is absent, so a minimal PATH cannot select the system Python.
23
+ - A DeepSeek Harness install on the supported line: `0.1.5-rc.1` up to, but
24
+ not including, `0.3.0` and its prereleases, verified against `0.1.5-rc.2`,
25
+ `0.1.5-rc.3`, `0.1.7-rc.2`, `0.2.0-rc.2`, `0.2.1-rc.2`, `0.2.1-rc.3`,
26
+ `0.2.1-rc.5`, `0.2.2-rc.1`, and `0.2.2-rc.5`. The range in `package.json`
27
+ spells one `>=lower <upper-0` alternative per line, so npm and the harness
28
+ read it the same way (see [RELEASE.md](RELEASE.md#harness-matrix)). The
29
+ plugin declares that range as a peer dependency, so a profile resolves the
30
+ harness copy it already has rather than a second framework instance, and
31
+ `dsh.compatibility.dshReleases` names the releases that passed the gates —
32
+ the harness refuses an install whose peer range does not cover it.
19
33
 
20
34
  ## Configuration
21
35
 
@@ -23,7 +37,7 @@ Every shipped setting keeps its meaning; this backend adds two fields and one
23
37
  per-route override.
24
38
 
25
39
  | Field | Default | Meaning |
26
- |---|---|---|
40
+ | --- | --- | --- |
27
41
  | `thresholdTokens` | — | Absolute trigger budget in tokens. Omitted means the ratio trigger alone. |
28
42
  | `retainShare` | `0.2` | Retained tail as a fraction of the derived trigger, applied only when the budget is what triggers condensation. |
29
43
  | `modelPolicies[].thresholdTokens` | — | Budget for one exact `provider`/`model` route. |
@@ -43,7 +57,7 @@ per-route override.
43
57
  ## Trigger examples
44
58
 
45
59
  | Context window | `thresholdRatio` | `thresholdTokens` | Trigger |
46
- |---|---|---|---|
60
+ | --- | --- | --- | --- |
47
61
  | 1,000,000 | 0.8 | 200,000 | **200,000** (budget) |
48
62
  | 262,144 | 0.8 | 200,000 | **200,000** (budget) |
49
63
  | 131,072 | 0.8 | 200,000 | 104,857 (ratio) |
@@ -121,7 +135,7 @@ the same task, the same route, and a reported window of 1,000,000 tokens, where
121
135
  the shipped ratio trigger is 800,000:
122
136
 
123
137
  | Run | `thresholdTokens` | Compaction events |
124
- |---|---|---|
138
+ | --- | --- | --- |
125
139
  | A | 8,000 | 4 starts, 3 summaries, 1 prune |
126
140
  | B | — | none |
127
141
 
@@ -162,14 +176,43 @@ source change.
162
176
 
163
177
  ## Releasing
164
178
 
165
- Published artefacts carry a provenance attestation, which only a CI provider can issue, so releases ship from the tag workflow rather than a laptop.
179
+ Published artefacts carry a provenance attestation, which only a CI provider can
180
+ issue, so releases ship from the tag workflow rather than a laptop.
166
181
 
167
- 1. Bump `version` in `package.json`, land it on `main` through a reviewed PR, and wait for CI to pass on the merged SHA.
168
- 2. Tag that SHA with a signed tag and push it. The tag ruleset admits repository admins only.
169
- 3. [`.github/workflows/release.yml`](.github/workflows/release.yml) re-runs the checks and the package smoke; the publish job then waits for a maintainer's approval on the `npm-release` environment before it publishes with OIDC trusted publishing and automatic provenance.
182
+ 1. Bump `version` in `package.json`, and push it to `main` after the local hooks
183
+ pass.
184
+ 2. Tag that SHA with a signed tag and push it. The tag ruleset admits repository
185
+ admins only.
186
+ 3. [`.github/workflows/release.yml`](.github/workflows/release.yml) re-runs the
187
+ checks and the package smoke; the publish job then publishes automatically
188
+ with OIDC trusted publishing and automatic provenance. The admin-only tag
189
+ ruleset makes the signed tag push the release approval, so the `npm-release`
190
+ environment has no manual approval step.
170
191
 
171
- The workflow stores no npm token: the registry trusts `release.yml` on the `npm-release` environment, and [`scripts/npm/release.py`](scripts/npm/release.py) creates both the environment and that trust. The full runbook is [RELEASE.md](RELEASE.md).
192
+ The workflow stores no npm token: the registry trusts `release.yml` on the
193
+ `npm-release` environment, and
194
+ [`scripts/npm/release.py`](scripts/npm/release.py) creates both the environment
195
+ and that trust. The full runbook is [RELEASE.md](RELEASE.md).
172
196
 
173
197
  ## License
174
198
 
175
199
  MIT
200
+
201
+ ## Git hooks
202
+
203
+ Checks run in tracked local Git hooks instead of push/PR CI. Run
204
+ `scripts/setup-hooks` once after cloning; it points this clone's
205
+ `core.hooksPath` at `.githooks`. Each hook runs the generic checks first
206
+ (sign-off and commit message format, a gitleaks secret scan, and signed,
207
+ signed-off commits on push), then this repository's checks in
208
+ `.githooks/<hook>.d/` in name order. Install
209
+ [gitleaks](https://github.com/gitleaks/gitleaks) first. Every check must pass
210
+ before you push; never use `--no-verify`. Pre-push checks test exactly each
211
+ pushed commit: in place only when it is the clean, unmodified checkout,
212
+ otherwise in a temporary worktree of that commit.
213
+
214
+ This repository's checks:
215
+
216
+ - `pre-commit`: staged whitespace and conflict-marker check.
217
+ - `pre-push`: `npm audit signatures`, `pnpm run check`,
218
+ `pnpm audit --audit-level high`.
package/dist/config.js CHANGED
@@ -3,8 +3,8 @@
3
3
  * budget.
4
4
  * @module @sagmans/dsh-auto-compact/config
5
5
  */
6
- import Schema from '@deepseek-ai/schemastery';
7
6
  import { BasicCompactionEngine } from '@deepseek-ai/dsh-compaction-basic';
7
+ import Schema from '@deepseek-ai/schemastery';
8
8
  /** Tail share of the derived threshold used when no explicit share is configured. */
9
9
  export const DEFAULT_RETAIN_SHARE = 0.2;
10
10
  const thresholdTokensSchema = Schema.number().step(1).min(1);
package/dist/index.js CHANGED
@@ -8,11 +8,11 @@
8
8
  * @module @sagmans/dsh-auto-compact
9
9
  */
10
10
  import { BasicCompactionEngine } from '@deepseek-ai/dsh-compaction-basic';
11
- import { Config, resolveCapPolicy, routeKey, toEngineConfig } from "./config.js";
12
- import { decidePressurePolicy, routePolicyTerms } from "./policy.js";
13
- import { derivedConfig, findOverride, resolveContextWindow, routedTarget, withDerivedPolicy, } from "./view.js";
14
- export { Config, DEFAULT_RETAIN_SHARE, resolveCapPolicy, routeKey, toEngineConfig } from "./config.js";
15
- export { decidePressurePolicy, routePolicyTerms } from "./policy.js";
11
+ import { Config, resolveCapPolicy, routeKey, toEngineConfig } from './config.js';
12
+ import { decidePressurePolicy, routePolicyTerms } from './policy.js';
13
+ import { derivedConfig, findOverride, resolveContextWindow, routedTarget, withDerivedPolicy, } from './view.js';
14
+ export { Config, DEFAULT_RETAIN_SHARE, resolveCapPolicy, routeKey, toEngineConfig, } from './config.js';
15
+ export { decidePressurePolicy, routePolicyTerms } from './policy.js';
16
16
  /**
17
17
  * Shipped compaction backend plus an absolute token budget.
18
18
  *
@@ -49,8 +49,8 @@ export class AutoCompactEngine extends BasicCompactionEngine {
49
49
  const target = trigger === 'pressure' ? routedTarget(agent.session) : undefined;
50
50
  const cap = target === undefined
51
51
  ? undefined
52
- : this.capPolicy.routeCaps.get(routeKey(target.provider, target.model))
53
- ?? this.capPolicy.defaultCap;
52
+ : (this.capPolicy.routeCaps.get(routeKey(target.provider, target.model)) ??
53
+ this.capPolicy.defaultCap);
54
54
  const measured = cap === undefined ? 0 : this.ctx.tokenMeter.measure(agent.session).totalTokens;
55
55
  // The derived trigger never exceeds the budget, so below it there is nothing
56
56
  // to decide and no capacity lookup is worth making on every step.
@@ -76,13 +76,13 @@ export class AutoCompactEngine extends BasicCompactionEngine {
76
76
  });
77
77
  if (derived === undefined)
78
78
  return super.compactIfNeeded(agent, trigger, signal);
79
- this.ctx.logger.debug(`auto-compact: ${target.provider}/${target.model} pressure ${measured}, `
80
- + `ratio trigger ${Math.floor(contextWindow * terms.thresholdRatio)} on window ${contextWindow}, `
81
- + `absolute budget ${cap} -> threshold ${derived.thresholdTokens}, tail ${derived.retainTokens}`);
82
- const result = await withDerivedPolicy(this, derivedConfig(this.config, override, derived), view => BasicCompactionEngine.prototype.compactIfNeeded.call(view, agent, trigger, signal));
79
+ this.ctx.logger.debug(`auto-compact: ${target.provider}/${target.model} pressure ${measured}, ` +
80
+ `ratio trigger ${Math.floor(contextWindow * terms.thresholdRatio)} on window ${contextWindow}, ` +
81
+ `absolute budget ${cap} -> threshold ${derived.thresholdTokens}, tail ${derived.retainTokens}`);
82
+ const result = await withDerivedPolicy(this, derivedConfig(this.config, override, derived), (view) => BasicCompactionEngine.prototype.compactIfNeeded.call(view, agent, trigger, signal));
83
83
  if (result !== null) {
84
- this.ctx.logger.info(`auto-compact: condensed at the absolute budget of ${derived.thresholdTokens} tokens `
85
- + `(window ${contextWindow}, tail ${derived.retainTokens})`);
84
+ this.ctx.logger.info(`auto-compact: condensed at the absolute budget of ${derived.thresholdTokens} tokens ` +
85
+ `(window ${contextWindow}, tail ${derived.retainTokens})`);
86
86
  }
87
87
  return result;
88
88
  }
package/dist/view.js CHANGED
@@ -21,7 +21,7 @@ export function routedTarget(session) {
21
21
  * @returns the matching override, or `undefined`.
22
22
  */
23
23
  export function findOverride(policies, target) {
24
- return policies.find(policy => policy.provider === target.provider && policy.model === target.model);
24
+ return policies.find((policy) => policy.provider === target.provider && policy.model === target.model);
25
25
  }
26
26
  /**
27
27
  * Read the routed model's adapter-owned capacity.
@@ -31,7 +31,8 @@ export function findOverride(policies, target) {
31
31
  * @returns the reported window, or `undefined` when the adapter declares none.
32
32
  */
33
33
  export async function resolveContextWindow(ctx, target, signal) {
34
- return (await ctx.llm.resolveModelInfo(target.provider, target.model, signal)).context?.contextWindow;
34
+ return (await ctx.llm.resolveModelInfo(target.provider, target.model, signal)).context
35
+ ?.contextWindow;
35
36
  }
36
37
  /**
37
38
  * Build the complete policy the shipped transaction must run under.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sagmans/dsh-auto-compact",
3
- "version": "0.2.0",
3
+ "version": "0.3.1",
4
4
  "description": "Absolute token trigger for DeepSeek Harness automatic compaction: condense at a fixed token budget or at the model window ratio, whichever comes first.",
5
5
  "keywords": [
6
6
  "deepseek-harness",
@@ -24,7 +24,7 @@
24
24
  "README.md"
25
25
  ],
26
26
  "engines": {
27
- "node": "^24.0.0"
27
+ "node": ">=22.19.0"
28
28
  },
29
29
  "packageManager": "pnpm@11.21.0",
30
30
  "publishConfig": {
@@ -42,12 +42,17 @@
42
42
  "patch": "./cordis.patch.yml"
43
43
  },
44
44
  "compatibility": {
45
- "dsh": ">=0.1.5-rc.1 <0.3.0",
45
+ "dsh": ">=0.1.5-rc.1 <0.1.6-0 || >=0.1.6-0 <0.1.7-0 || >=0.1.7-0 <0.2.0-0 || >=0.2.0-0 <0.2.1-0 || >=0.2.1-0 <0.2.2-0 || >=0.2.2-0 <0.3.0-0",
46
46
  "dshReleases": {
47
47
  "0.1.5-rc.2": "compatible",
48
48
  "0.1.5-rc.3": "compatible",
49
49
  "0.1.7-rc.2": "compatible",
50
- "0.2.0-rc.2": "compatible"
50
+ "0.2.0-rc.2": "compatible",
51
+ "0.2.1-rc.2": "compatible",
52
+ "0.2.1-rc.3": "compatible",
53
+ "0.2.1-rc.5": "compatible",
54
+ "0.2.2-rc.1": "compatible",
55
+ "0.2.2-rc.5": "compatible"
51
56
  }
52
57
  }
53
58
  },
@@ -56,35 +61,42 @@
56
61
  "test": "node --import tsx/esm --test \"tests/*.spec.ts\"",
57
62
  "build": "tsc -p tsconfig.build.json",
58
63
  "test:build": "node --test \"tests/*.test.mjs\"",
59
- "test:release": "python3 -m unittest discover -s tests/release -p 'test_*.py'",
64
+ "test:release": "uv run --no-project --python-preference only-managed python -m unittest discover -s tests/release -p 'test_*.py'",
60
65
  "pack-smoke": "node tools/pack-smoke.mjs",
61
66
  "matrix": "node tools/harness-matrix.mjs",
62
- "check": "pnpm run typecheck && pnpm test && pnpm run build && pnpm run test:build && pnpm test:release && pnpm run pack-smoke && pnpm run matrix",
67
+ "check:tools": "bash scripts/stack-checks.sh tools",
68
+ "lint": "biome ci --error-on-warnings .",
69
+ "lint:fix": "biome check --write .",
70
+ "lint:py": "bash scripts/stack-checks.sh py-lint",
71
+ "typecheck:py": "bash scripts/stack-checks.sh py-typecheck",
72
+ "lint:sh": "bash scripts/stack-checks.sh sh",
73
+ "check": "pnpm run check:tools && node tools/python-policy.mjs && pnpm run lint && pnpm run lint:py && pnpm run typecheck:py && pnpm run lint:sh && pnpm run typecheck && pnpm test && pnpm run build && pnpm run test:build && pnpm test:release && pnpm run pack-smoke && pnpm run matrix",
63
74
  "prepack": "pnpm run build",
64
75
  "prepublishOnly": "pnpm run typecheck && pnpm test && pnpm test:release"
65
76
  },
66
77
  "peerDependencies": {
67
- "@deepseek-ai/cordis": "^4.0.2",
68
- "@deepseek-ai/dsh-agent": ">=0.1.5-rc.1 <0.3.0",
69
- "@deepseek-ai/dsh-compaction": ">=0.1.5-rc.1 <0.3.0",
70
- "@deepseek-ai/dsh-compaction-basic": ">=0.1.5-rc.1 <0.3.0",
71
- "@deepseek-ai/dsh-llm": ">=0.1.5-rc.1 <0.3.0",
72
- "@deepseek-ai/dsh-session": ">=0.1.5-rc.1 <0.3.0",
73
- "@deepseek-ai/dsh-token-meter": ">=0.1.5-rc.1 <0.3.0",
74
- "@deepseek-ai/schemastery": "^3.18.2"
78
+ "@deepseek-ai/cordis": ">=4.0.2 <4.2.0-0",
79
+ "@deepseek-ai/dsh-agent": ">=0.1.5-rc.1 <0.1.6-0 || >=0.1.6-0 <0.1.7-0 || >=0.1.7-0 <0.2.0-0 || >=0.2.0-0 <0.2.1-0 || >=0.2.1-0 <0.2.2-0 || >=0.2.2-0 <0.3.0-0",
80
+ "@deepseek-ai/dsh-compaction": ">=0.1.5-rc.1 <0.1.6-0 || >=0.1.6-0 <0.1.7-0 || >=0.1.7-0 <0.2.0-0 || >=0.2.0-0 <0.2.1-0 || >=0.2.1-0 <0.2.2-0 || >=0.2.2-0 <0.3.0-0",
81
+ "@deepseek-ai/dsh-compaction-basic": ">=0.1.5-rc.1 <0.1.6-0 || >=0.1.6-0 <0.1.7-0 || >=0.1.7-0 <0.2.0-0 || >=0.2.0-0 <0.2.1-0 || >=0.2.1-0 <0.2.2-0 || >=0.2.2-0 <0.3.0-0",
82
+ "@deepseek-ai/dsh-llm": ">=0.1.5-rc.1 <0.1.6-0 || >=0.1.6-0 <0.1.7-0 || >=0.1.7-0 <0.2.0-0 || >=0.2.0-0 <0.2.1-0 || >=0.2.1-0 <0.2.2-0 || >=0.2.2-0 <0.3.0-0",
83
+ "@deepseek-ai/dsh-session": ">=0.1.5-rc.1 <0.1.6-0 || >=0.1.6-0 <0.1.7-0 || >=0.1.7-0 <0.2.0-0 || >=0.2.0-0 <0.2.1-0 || >=0.2.1-0 <0.2.2-0 || >=0.2.2-0 <0.3.0-0",
84
+ "@deepseek-ai/dsh-token-meter": ">=0.1.5-rc.1 <0.1.6-0 || >=0.1.6-0 <0.1.7-0 || >=0.1.7-0 <0.2.0-0 || >=0.2.0-0 <0.2.1-0 || >=0.2.1-0 <0.2.2-0 || >=0.2.2-0 <0.3.0-0",
85
+ "@deepseek-ai/schemastery": ">=3.18.2 <3.20.0-0"
75
86
  },
76
87
  "devDependencies": {
77
- "@deepseek-ai/cordis": "4.0.2",
78
- "@deepseek-ai/dsh": "0.2.0-rc.2",
79
- "@deepseek-ai/dsh-agent": "0.2.0-rc.2",
80
- "@deepseek-ai/dsh-compaction": "0.2.0-rc.2",
81
- "@deepseek-ai/dsh-compaction-basic": "0.2.0-rc.2",
82
- "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
83
- "@deepseek-ai/dsh-session": "0.2.0-rc.2",
84
- "@deepseek-ai/dsh-token-meter": "0.2.0-rc.2",
85
- "@deepseek-ai/schemastery": "3.18.2",
86
- "@types/node": "22.20.0",
87
- "tsx": "4.22.4",
88
- "typescript": "6.0.3"
88
+ "@biomejs/biome": "2.6.3",
89
+ "@deepseek-ai/cordis": "4.1.0",
90
+ "@deepseek-ai/dsh": "0.2.2-rc.5",
91
+ "@deepseek-ai/dsh-agent": "0.2.2-rc.5",
92
+ "@deepseek-ai/dsh-compaction": "0.2.2-rc.5",
93
+ "@deepseek-ai/dsh-compaction-basic": "0.2.2-rc.5",
94
+ "@deepseek-ai/dsh-llm": "0.2.2-rc.5",
95
+ "@deepseek-ai/dsh-session": "0.2.2-rc.5",
96
+ "@deepseek-ai/dsh-token-meter": "0.2.2-rc.5",
97
+ "@deepseek-ai/schemastery": "3.19.0",
98
+ "@types/node": "26.6.5",
99
+ "tsx": "4.23.15",
100
+ "typescript": "7.0.2"
89
101
  }
90
102
  }