dvalincode 0.21.0 → 0.22.0
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 +209 -4
- package/README.zh-CN.md +160 -4
- package/dist/agent/compact.d.ts +8 -0
- package/dist/agent/compact.js +44 -5
- package/dist/agent/compact.js.map +1 -1
- package/dist/agent/loop.d.ts +5 -0
- package/dist/agent/loop.js +16 -7
- package/dist/agent/loop.js.map +1 -1
- package/dist/agent/runner.d.ts +4 -3
- package/dist/agent/runner.js +81 -8
- package/dist/agent/runner.js.map +1 -1
- package/dist/agent/session.d.ts +7 -0
- package/dist/agent/session.js +27 -1
- package/dist/agent/session.js.map +1 -1
- package/dist/agent/types.d.ts +5 -1
- package/dist/agent/types.js.map +1 -1
- package/dist/audit/log.d.ts +5 -1
- package/dist/audit/log.js.map +1 -1
- package/dist/commands/dvalin.d.ts +7 -1
- package/dist/commands/dvalin.js +209 -9
- package/dist/commands/dvalin.js.map +1 -1
- package/dist/commands/provider.js +2 -0
- package/dist/commands/provider.js.map +1 -1
- package/dist/commands/run.js +4 -2
- package/dist/commands/run.js.map +1 -1
- package/dist/commands/security.d.ts +2 -0
- package/dist/commands/security.js +228 -14
- package/dist/commands/security.js.map +1 -1
- package/dist/harness/run.d.ts +8 -2
- package/dist/harness/run.js +1 -1
- package/dist/harness/run.js.map +1 -1
- package/dist/mcp/server.js +5 -2
- package/dist/mcp/server.js.map +1 -1
- package/dist/providers/anthropic.js +14 -2
- package/dist/providers/anthropic.js.map +1 -1
- package/dist/providers/openaiCompatible.js +7 -6
- package/dist/providers/openaiCompatible.js.map +1 -1
- package/dist/providers/retry.d.ts +32 -0
- package/dist/providers/retry.js +150 -0
- package/dist/providers/retry.js.map +1 -0
- package/dist/providers/types.d.ts +10 -0
- package/dist/remediation/automate.d.ts +1 -1
- package/dist/remediation/automate.js +2 -1
- package/dist/remediation/automate.js.map +1 -1
- package/dist/remediation/codeQualityExport.d.ts +25 -0
- package/dist/remediation/codeQualityExport.js +24 -0
- package/dist/remediation/codeQualityExport.js.map +1 -0
- package/dist/remediation/evasion.d.ts +61 -0
- package/dist/remediation/evasion.js +190 -0
- package/dist/remediation/evasion.js.map +1 -0
- package/dist/remediation/fixLoop.d.ts +255 -0
- package/dist/remediation/fixLoop.js +639 -0
- package/dist/remediation/fixLoop.js.map +1 -0
- package/dist/remediation/fixLoopStats.d.ts +93 -0
- package/dist/remediation/fixLoopStats.js +244 -0
- package/dist/remediation/fixLoopStats.js.map +1 -0
- package/dist/remediation/rebase.d.ts +44 -0
- package/dist/remediation/rebase.js +114 -0
- package/dist/remediation/rebase.js.map +1 -0
- package/dist/remediation/reproduce.d.ts +47 -0
- package/dist/remediation/reproduce.js +75 -0
- package/dist/remediation/reproduce.js.map +1 -0
- package/dist/remediation/sarif.d.ts +4 -1
- package/dist/remediation/sarif.js +19 -1
- package/dist/remediation/sarif.js.map +1 -1
- package/dist/remediation/scannerSuite.d.ts +51 -3
- package/dist/remediation/scannerSuite.js +346 -87
- package/dist/remediation/scannerSuite.js.map +1 -1
- package/dist/remediation/verify.d.ts +8 -0
- package/dist/remediation/verify.js +24 -11
- package/dist/remediation/verify.js.map +1 -1
- package/dist/security/config.d.ts +8 -2
- package/dist/security/config.js +10 -3
- package/dist/security/config.js.map +1 -1
- package/dist/security/contracts.js +15 -0
- package/dist/security/contracts.js.map +1 -1
- package/dist/security/fixRecord.d.ts +103 -8
- package/dist/security/fixRecord.js +113 -11
- package/dist/security/fixRecord.js.map +1 -1
- package/dist/security/fixRecordFile.d.ts +11 -2
- package/dist/security/fixRecordFile.js +20 -2
- package/dist/security/fixRecordFile.js.map +1 -1
- package/dist/security/fixRecordSignature.d.ts +104 -0
- package/dist/security/fixRecordSignature.js +227 -0
- package/dist/security/fixRecordSignature.js.map +1 -0
- package/dist/security/guardedScan.d.ts +39 -0
- package/dist/security/guardedScan.js +45 -0
- package/dist/security/guardedScan.js.map +1 -0
- package/dist/security/onboarding.d.ts +28 -0
- package/dist/security/onboarding.js +124 -0
- package/dist/security/onboarding.js.map +1 -0
- package/dist/security/reproduceInCi.d.ts +44 -0
- package/dist/security/reproduceInCi.js +96 -0
- package/dist/security/reproduceInCi.js.map +1 -0
- package/dist/security/reverify.d.ts +130 -0
- package/dist/security/reverify.js +361 -0
- package/dist/security/reverify.js.map +1 -0
- package/dist/security/suppressionGuard.d.ts +58 -0
- package/dist/security/suppressionGuard.js +216 -0
- package/dist/security/suppressionGuard.js.map +1 -0
- package/dist/security/verifyRun.js +14 -3
- package/dist/security/verifyRun.js.map +1 -1
- package/dist/security/workflow.d.ts +11 -1
- package/dist/security/workflow.js +2 -0
- package/dist/security/workflow.js.map +1 -1
- package/dist/server/routes/config.js +2 -0
- package/dist/server/routes/config.js.map +1 -1
- package/dist/server/routes/remediation.js +6 -5
- package/dist/server/routes/remediation.js.map +1 -1
- package/dist/tools/editFile.js +9 -2
- package/dist/tools/editFile.js.map +1 -1
- package/dist/tools/registry.d.ts +4 -1
- package/dist/tools/registry.js +29 -9
- package/dist/tools/registry.js.map +1 -1
- package/dist/tools/runSecuritySuite.d.ts +3 -0
- package/dist/tools/runSecuritySuite.js +2 -2
- package/dist/tools/runSecuritySuite.js.map +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -90,6 +90,155 @@ dvalin scanners install semgrep # review the command
|
|
|
90
90
|
dvalin scanners install semgrep --yes # execute it under Dvalin policy
|
|
91
91
|
```
|
|
92
92
|
|
|
93
|
+
### Make it the gate in one step
|
|
94
|
+
|
|
95
|
+
```sh
|
|
96
|
+
dvalin init
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
`init` writes `dvalin.security.json` (fail on *new* findings at high or above),
|
|
100
|
+
names the checks your project actually has (`test`, `typecheck`, `build`,
|
|
101
|
+
`lint`) as what Dvalin runs before it calls a fix verified, records today's
|
|
102
|
+
findings as the accepted backlog in `.dvalin/baseline.json`, and writes a CI
|
|
103
|
+
gate for GitHub (`.github/workflows/dvalin.yml`) or GitLab
|
|
104
|
+
(`.gitlab/dvalin-security.yml`, with a Code Quality report for the merge
|
|
105
|
+
request widget). It never overwrites a file that is already there unless you
|
|
106
|
+
pass `--force`. Commit what it wrote, and the backlog stops blocking anyone:
|
|
107
|
+
only what a change adds fails.
|
|
108
|
+
|
|
109
|
+
To gate every commit locally too, add the [pre-commit](https://pre-commit.com) hook:
|
|
110
|
+
|
|
111
|
+
```yaml
|
|
112
|
+
# .pre-commit-config.yaml
|
|
113
|
+
repos:
|
|
114
|
+
- repo: https://github.com/arthurpanhku/dvalincode
|
|
115
|
+
rev: v0.22.0 # the hook ships in v0.22.0
|
|
116
|
+
hooks:
|
|
117
|
+
- id: dvalin-scan # or dvalin-scan-installed, to use the CLI you installed
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### Measure with the scanner your CI gate uses
|
|
121
|
+
|
|
122
|
+
If Snyk is what blocks your merges, verify against Snyk. A fix judged "clean"
|
|
123
|
+
by a different engine is a fix the gate can still reject, and that mismatch is
|
|
124
|
+
what turns one agent repair into several rounds of push, fail, and rebase.
|
|
125
|
+
|
|
126
|
+
```sh
|
|
127
|
+
npm install -g snyk && snyk auth # or set SNYK_TOKEN
|
|
128
|
+
dvalin scan . --scanners builtin,snyk-code,snyk-oss
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
`snyk-code` (SAST) and `snyk-oss` (dependencies) are engines like any other:
|
|
132
|
+
their findings carry the same fingerprints, coverage and gate, and a failed
|
|
133
|
+
login is reported as an engine error, which makes the scan `partial`, never
|
|
134
|
+
clean. They run only when named, because Snyk Code uploads source to Snyk.
|
|
135
|
+
Name them in `dvalin.security.json` to make them part of the policy, and
|
|
136
|
+
`reverify` will judge every fix with them.
|
|
137
|
+
|
|
138
|
+
If GitHub code scanning is the gate, use CodeQL the same way:
|
|
139
|
+
|
|
140
|
+
```sh
|
|
141
|
+
dvalin scan . --scanners builtin,codeql
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
`codeql` builds one database per language outside the workspace and runs that
|
|
145
|
+
language's default code-scanning queries, so its findings are the ones the gate
|
|
146
|
+
reports. JavaScript/TypeScript, Python, Ruby, Java and C# are analysed without a
|
|
147
|
+
build; Go uses CodeQL's autobuild. Kotlin, C/C++ and Swift need the project's own
|
|
148
|
+
build, so when they are in the tree the run says so and the scan is `partial`,
|
|
149
|
+
not clean. It runs only when named — a database takes minutes, not seconds, and
|
|
150
|
+
the CodeQL CLI's license covers open-source code and GitHub Advanced Security
|
|
151
|
+
customers.
|
|
152
|
+
|
|
153
|
+
Ignores Snyk itself reports as accepted are honored and listed as coverage
|
|
154
|
+
exclusions. Ignores **the change under review adds** are not: when a fix is
|
|
155
|
+
judged, `.snyk`, `.semgrepignore`, `.trivyignore` and `.dvalincodeignore` are
|
|
156
|
+
restored to the base commit's version and new inline markers (`deepcode
|
|
157
|
+
ignore`, `nosemgrep`, `nosec`, `NOSONAR`, …) are blanked, so a finding that was
|
|
158
|
+
silenced rather than fixed still fails the fix. A suppression is a risk
|
|
159
|
+
decision a person makes in its own change, never a repair.
|
|
160
|
+
|
|
161
|
+
The same judgement applies wherever Dvalin says "verified": the fix loop,
|
|
162
|
+
`dvalin verify`, the MCP `dvalin_verify_findings` tool, single-round
|
|
163
|
+
`--fix --verify`, and CI `reverify`. Those records are `dvalin-fix-record/v3`,
|
|
164
|
+
which also fails a repair that hid a finding instead of fixing it — a sibling
|
|
165
|
+
sink, a deleted vulnerable file, deleted tests or assertions. Outside a git
|
|
166
|
+
repository, where the change cannot be determined, records stay v2 and say
|
|
167
|
+
that evasion was not evaluated.
|
|
168
|
+
|
|
169
|
+
### Let it loop until the gate would pass
|
|
170
|
+
|
|
171
|
+
```sh
|
|
172
|
+
dvalincode dvalin . --scanners builtin,snyk-code,snyk-oss --until-clean --max-rounds 3 --executor codex
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
`--until-clean` turns one fix attempt into a bounded loop. The executor edits;
|
|
176
|
+
Dvalin re-scans with the same engines and runs the project's checks itself;
|
|
177
|
+
the executor is sent **only what is still wrong** — targets still present,
|
|
178
|
+
findings its change introduced, failing checks with their last lines of
|
|
179
|
+
output, suppressions it added — and fixes again. Dependency findings go first.
|
|
180
|
+
|
|
181
|
+
The loop stops, and says which, when every target is gone with nothing
|
|
182
|
+
blocking introduced and every check passing (`verified`), when the round
|
|
183
|
+
budget runs out, when a round leaves the same problems open or the open set
|
|
184
|
+
stops shrinking (`stalled`), when the targets need a person — a dependency
|
|
185
|
+
with no fixed version (`not-auto-fixable`) — or when the engines or checks
|
|
186
|
+
cannot run (`unverifiable`). Suppressions the executor adds are undone before
|
|
187
|
+
each scan and stay open problems until removed. Every outcome issues a fix
|
|
188
|
+
record, and every round is logged under `~/.dvalincode/security/fix-loops/`;
|
|
189
|
+
`dvalin loop-stats` summarizes those logs — how often loops reach `verified`,
|
|
190
|
+
the median and p90 rounds to green, which stop rule fired, and what was still
|
|
191
|
+
open when a loop stalled (`--json`, `--since`, `--executor` to slice it).
|
|
192
|
+
|
|
193
|
+
Rounds are kept short without changing what decides them. The engines run side
|
|
194
|
+
by side, so a scan costs the slowest engine rather than the sum. Between rounds,
|
|
195
|
+
the engines that analyse one file at a time (Dvalin Built-in, Semgrep) rescan
|
|
196
|
+
only the files the change touched and the files the targets are in; the others
|
|
197
|
+
always scan the whole tree. That narrowed scan only steers the executor: any
|
|
198
|
+
round that would stop the loop is re-judged on a full scan of the same tree, and
|
|
199
|
+
only the full scan decides the outcome and goes into the record.
|
|
200
|
+
`--full-rescan` scans everything every round, and `loop-stats` reports scan time
|
|
201
|
+
per round and how often a full scan changed the decision.
|
|
202
|
+
|
|
203
|
+
For **code** findings the loop first asks for a reproduction: tests only, which
|
|
204
|
+
Dvalin runs on the unfixed code and requires to fail — by a failing assertion,
|
|
205
|
+
not a missing runner or a not-yet-written import. The tests are hashed; the
|
|
206
|
+
fix must then make them pass **unchanged**, and that run is a check in the
|
|
207
|
+
record. A finding no test could demonstrate stops the loop as
|
|
208
|
+
`not-reproduced` before anything is fixed: it may be a false positive, and a
|
|
209
|
+
person triages it. The runner is inferred (vitest, jest, mocha, `node --test`,
|
|
210
|
+
pytest, `go test`) or set with `--repro-command 'npx vitest run {files}'` or
|
|
211
|
+
`reproduce` in `dvalin.security.json` — never chosen by the executor.
|
|
212
|
+
|
|
213
|
+
Each fix round also rejects the evasions an agent reaches for when the goal is
|
|
214
|
+
"the scanner went quiet": moving the sink to a sibling (`eval` →
|
|
215
|
+
`new Function`, `exec` → `spawn` with `shell: true`), deleting the vulnerable
|
|
216
|
+
file, deleting tests, removing assertions. In practice the scanner alone is
|
|
217
|
+
fooled by the first one — the rule stops matching — and the reproduction test
|
|
218
|
+
and the evasion check are what catch it.
|
|
219
|
+
|
|
220
|
+
### Keep it on today's main, and close it in CI
|
|
221
|
+
|
|
222
|
+
```sh
|
|
223
|
+
dvalincode dvalin . --scanners builtin,snyk-code,snyk-oss --until-clean \
|
|
224
|
+
--rebase-onto origin/main --executor codex --draft-pr --sign-key ci.key
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
With `--rebase-onto` the loop fetches and rebases the fix onto upstream before
|
|
228
|
+
it starts and after every round, then judges it there. Conflicts go to the
|
|
229
|
+
executor — the conflicted files only, with "do not run git" — and Dvalin
|
|
230
|
+
continues the rebase itself; markers left in a file are a conflict not
|
|
231
|
+
resolved. If they cannot be resolved the rebase is aborted, the tree is left as
|
|
232
|
+
it was, and the loop stops as `rebase-conflict`. After each rebase the baseline
|
|
233
|
+
is re-scanned on the new base, so a finding a teammate landed on main is not
|
|
234
|
+
blamed on the fix.
|
|
235
|
+
|
|
236
|
+
`--draft-pr` commits the record at `.dvalin/fix-record.json`, and
|
|
237
|
+
[`docs/examples/dvalin-fix-loop.yml`](docs/examples/dvalin-fix-loop.yml)
|
|
238
|
+
re-executes it on the pull request with `reverify: true`: base and head
|
|
239
|
+
re-scanned, checks re-run, and the reproduction re-run with the fix reverted in
|
|
240
|
+
place (it must fail) and restored (it must pass) — then signed with the CI key.
|
|
241
|
+
|
|
93
242
|
For an incremental “no new high-risk findings” gate, commit the policy and
|
|
94
243
|
baseline with the repository:
|
|
95
244
|
|
|
@@ -114,7 +263,7 @@ steps:
|
|
|
114
263
|
- uses: actions/checkout@v5
|
|
115
264
|
with:
|
|
116
265
|
fetch-depth: 0 # so the scan can reach the base commit
|
|
117
|
-
- uses: arthurpanhku/dvalincode@v0.
|
|
266
|
+
- uses: arthurpanhku/dvalincode@v0.21.0
|
|
118
267
|
with:
|
|
119
268
|
fail-on: high
|
|
120
269
|
diff: true # only report on what this PR changed
|
|
@@ -138,7 +287,7 @@ engines were missing is not the same answer as "no findings" from a complete one
|
|
|
138
287
|
If your pipeline produced a fix record, hand it to the same action:
|
|
139
288
|
|
|
140
289
|
```yaml
|
|
141
|
-
- uses: arthurpanhku/dvalincode@v0.
|
|
290
|
+
- uses: arthurpanhku/dvalincode@v0.21.0
|
|
142
291
|
with:
|
|
143
292
|
fix-record: fix-record.json
|
|
144
293
|
```
|
|
@@ -146,7 +295,13 @@ If your pipeline produced a fix record, hand it to the same action:
|
|
|
146
295
|
The runner re-derives the record from the file alone — recomputing its hash and
|
|
147
296
|
re-deriving its verdict from its own evidence — and posts the result on the pull
|
|
148
297
|
request. A record that was edited after it was issued fails here, and fails the
|
|
149
|
-
job.
|
|
298
|
+
job.
|
|
299
|
+
|
|
300
|
+
Re-derivation proves the record is *self-consistent*. It cannot prove the record
|
|
301
|
+
was issued by anyone who actually ran anything: every field in it, the exit
|
|
302
|
+
codes included, is something a forger could write, and a self-consistent
|
|
303
|
+
forgery re-derives. Two things close that gap — re-execute the claim on the
|
|
304
|
+
runner, and sign what the runner observed.
|
|
150
305
|
|
|
151
306
|
```
|
|
152
307
|
🔏 Verified Fix Record
|
|
@@ -169,6 +324,52 @@ A repair that regressed says so in the same place, and fails the job with it:
|
|
|
169
324
|
- outcome: regressed
|
|
170
325
|
```
|
|
171
326
|
|
|
327
|
+
### Re-execute it on the runner, and sign what you saw
|
|
328
|
+
|
|
329
|
+
```yaml
|
|
330
|
+
- uses: actions/checkout@v5
|
|
331
|
+
with:
|
|
332
|
+
fetch-depth: 0 # the base commit has to be reachable
|
|
333
|
+
- run: npm ci # the project's checks run on the runner
|
|
334
|
+
- uses: arthurpanhku/dvalincode@v0.22.0 # reverify ships in v0.22.0; until it is tagged, pin a main commit SHA
|
|
335
|
+
with:
|
|
336
|
+
fix-record: fix-record.json
|
|
337
|
+
reverify: true
|
|
338
|
+
signing-key: ${{ secrets.DVALIN_SIGNING_KEY }} # optional
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
With `reverify: true` the claimed record contributes only *which targets* it
|
|
342
|
+
says it fixed and *who* the executor was. Everything else is observed again:
|
|
343
|
+
|
|
344
|
+
- the **base** commit is checked out and scanned, so each claimed target must
|
|
345
|
+
actually have existed there — a record cannot take credit for removing a
|
|
346
|
+
finding nobody had;
|
|
347
|
+
- the **head** is scanned, so "gone" is observed on the runner;
|
|
348
|
+
- the project's checks are run on the runner, with the checks, gate and
|
|
349
|
+
scanners read from the **base** commit's `dvalin.security.json` — a pull
|
|
350
|
+
request that relaxes its own gate or deletes its own checks is judged under
|
|
351
|
+
the rules it is trying to change;
|
|
352
|
+
- a fresh record is issued from those observations, and the job fails unless it
|
|
353
|
+
verifies.
|
|
354
|
+
|
|
355
|
+
With `signing-key` the fresh record is signed (Ed25519, over its hash). The key
|
|
356
|
+
is taken into memory and removed from the environment before the project's
|
|
357
|
+
checks run, so the code under review cannot read it. Downstream — a release
|
|
358
|
+
job, another repository, an auditor — can then require that signature:
|
|
359
|
+
|
|
360
|
+
```sh
|
|
361
|
+
dvalin keygen --out ci # once; store ci.key as a secret, publish ci.pub
|
|
362
|
+
dvalin verify-fix record.json --trusted-key ci.pub
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
A record that is unsigned, or signed only by a key you did not name, fails
|
|
366
|
+
under `--trusted-key`. A valid signature says *which key vouched for this
|
|
367
|
+
record*; whether that key deserves trust is your decision, and the reason to
|
|
368
|
+
trust a CI key is that the CI job re-executed the verification rather than
|
|
369
|
+
copying it. Locally, `dvalin reverify <record> --base origin/main` runs the same
|
|
370
|
+
re-execution, and `dvalin sign-fix` signs a record that re-derives.
|
|
371
|
+
[FVP-1 §4a, §5a →](docs/spec/FIX-VERIFICATION.md)
|
|
372
|
+
|
|
172
373
|
### Or let your agent call it
|
|
173
374
|
|
|
174
375
|
If an agent is writing the code, something other than that agent has to check
|
|
@@ -238,6 +439,8 @@ One server, reached the way each tool expects:
|
|
|
238
439
|
| **Windsurf · Zed** | stdio MCP through their own settings — [server command](integrations/mcp/) |
|
|
239
440
|
| **Any MCP client** | [MCP registry](https://registry.modelcontextprotocol.io/): `io.github.arthurpanhku/dvalincode` |
|
|
240
441
|
| **GitHub Actions** | [Marketplace action](https://github.com/marketplace/actions/dvalin-security-scan) — findings inline on the pull request diff |
|
|
442
|
+
| **GitLab CI** | `dvalin init --ci gitlab` — new findings gate the merge request, shown in its Code Quality widget |
|
|
443
|
+
| **pre-commit** | [`dvalin-scan` hook](.pre-commit-hooks.yaml) — the same policy gate before every commit |
|
|
241
444
|
| **Any CI** | `dvalin scan . --fail-on high`, SARIF out for code scanning |
|
|
242
445
|
|
|
243
446
|
The MCP config formats are not interchangeable — VS Code keys its servers under
|
|
@@ -347,7 +550,8 @@ answer does not change depending on who asks it.
|
|
|
347
550
|
| **Reading it back** | VS Code | `mcp-install vscode` · [extension](editors/vscode/) for Problems, coverage and gate status | ✅ editor verified |
|
|
348
551
|
| **Gating the merge** | GitHub Actions | [Marketplace action](https://github.com/marketplace/actions/dvalin-security-scan) — findings on the diff, fix records re-derived on the runner | ✅ runs on this repository's own CI |
|
|
349
552
|
| | Any CI | `dvalin scan . --fail-on high`, SARIF out for code scanning | ✅ the exit code is the contract |
|
|
350
|
-
| **Believing the result** | anyone, offline | `dvalin verify-fix record.json` | ✅ no workspace, no network, no Dvalin state |
|
|
553
|
+
| **Believing the result** | anyone, offline | `dvalin verify-fix record.json --trusted-key ci.pub` | ✅ no workspace, no network, no Dvalin state |
|
|
554
|
+
| | the merge gate | `reverify: true` — base and head re-scanned, checks re-run on the runner, fresh record signed | ✅ covered by the test suite |
|
|
351
555
|
|
|
352
556
|
**✅** means a real client was driven end to end and the tool call was observed.
|
|
353
557
|
**⚙️** means the configuration is generated and its shape is tested, but no
|
|
@@ -1161,6 +1365,7 @@ Full source references: [docs/REFERENCES.md](docs/REFERENCES.md)
|
|
|
1161
1365
|
| badhope | [@weed33834](https://github.com/weed33834) |
|
|
1162
1366
|
| Samran Asif | [@webdevsamran](https://github.com/webdevsamran) |
|
|
1163
1367
|
| dchaudhari7177 | [@dchaudhari7177](https://github.com/dchaudhari7177) |
|
|
1368
|
+
| TayfurYldz | [@TayfurYldz](https://github.com/TayfurYldz) |
|
|
1164
1369
|
|
|
1165
1370
|
See the [complete contribution history](https://github.com/arthurpanhku/dvalincode/graphs/contributors), including automated dependency and maintenance updates.
|
|
1166
1371
|
|
package/README.zh-CN.md
CHANGED
|
@@ -80,6 +80,116 @@ dvalin scanners install semgrep # 只显示并审查命令
|
|
|
80
80
|
dvalin scanners install semgrep --yes # 在 Dvalin 策略约束下执行
|
|
81
81
|
```
|
|
82
82
|
|
|
83
|
+
### 一步变成门禁
|
|
84
|
+
|
|
85
|
+
```sh
|
|
86
|
+
dvalin init
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
`init` 会写入 `dvalin.security.json`(只对 high 及以上的*新增* finding 失败),把项目里真实存在的检查
|
|
90
|
+
(`test`、`typecheck`、`build`、`lint`)登记为 Dvalin 判定修复前要亲自运行的检查,把当前已有的
|
|
91
|
+
finding 记录为可接受的存量(`.dvalin/baseline.json`),并为 GitHub(`.github/workflows/dvalin.yml`)
|
|
92
|
+
或 GitLab(`.gitlab/dvalin-security.yml`,附带 MR 面板用的 Code Quality 报告)写好 CI 门禁。
|
|
93
|
+
已存在的文件不会被覆盖,除非加 `--force`。把它写出的文件提交上去,存量问题就不会再挡住任何人:
|
|
94
|
+
只有改动新增的问题才会失败。
|
|
95
|
+
|
|
96
|
+
想在本地每次提交前也把关,加上 [pre-commit](https://pre-commit.com) hook:
|
|
97
|
+
|
|
98
|
+
```yaml
|
|
99
|
+
# .pre-commit-config.yaml
|
|
100
|
+
repos:
|
|
101
|
+
- repo: https://github.com/arthurpanhku/dvalincode
|
|
102
|
+
rev: v0.22.0 # hook 随 v0.22.0 发布
|
|
103
|
+
hooks:
|
|
104
|
+
- id: dvalin-scan # PATH 上已有 dvalin 时用 dvalin-scan-installed
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### 用 CI 门禁同一把尺子来验证
|
|
108
|
+
|
|
109
|
+
如果卡你合并的是 Snyk,就用 Snyk 来验证。用别的引擎判定"干净"的修复,推上去照样可能被门禁拒绝 ——
|
|
110
|
+
一次 agent 修复变成"推送、失败、rebase"反复好几轮,往往就是因为两边尺子不一样。
|
|
111
|
+
|
|
112
|
+
```sh
|
|
113
|
+
npm install -g snyk && snyk auth # 或设置 SNYK_TOKEN
|
|
114
|
+
dvalin scan . --scanners builtin,snyk-code,snyk-oss
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
`snyk-code`(SAST)和 `snyk-oss`(依赖)与其他引擎完全同等:同样的指纹、覆盖度和门禁;
|
|
118
|
+
登录失败会作为引擎错误上报,扫描结果是 `partial`,绝不会显示成干净。它们只在被显式点名时运行,
|
|
119
|
+
因为 Snyk Code 会把源码上传到 Snyk。把它们写进 `dvalin.security.json` 就成为策略的一部分,
|
|
120
|
+
`reverify` 也会用它们评判每一次修复。
|
|
121
|
+
|
|
122
|
+
如果卡合并的是 GitHub code scanning,就同样用 CodeQL:
|
|
123
|
+
|
|
124
|
+
```sh
|
|
125
|
+
dvalin scan . --scanners builtin,codeql
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
`codeql` 会在 workspace 之外为每种语言建一个数据库,并跑该语言默认的 code-scanning 查询集,
|
|
129
|
+
所以它报的就是门禁会报的问题。JavaScript/TypeScript、Python、Ruby、Java、C# 无需构建即可分析;
|
|
130
|
+
Go 使用 CodeQL 的 autobuild。Kotlin、C/C++、Swift 需要项目自己的构建,树里有它们时运行结果会如实说明,
|
|
131
|
+
扫描是 `partial` 而不是干净。它只在被点名时运行 —— 建库要几分钟而不是几秒,而且 CodeQL CLI
|
|
132
|
+
的许可只覆盖开源代码和 GitHub Advanced Security 客户。
|
|
133
|
+
|
|
134
|
+
Snyk 自己标记为已接受的忽略会被尊重,并列入覆盖度的排除项。但**被审查的这次改动新增的**忽略不算数:
|
|
135
|
+
评判修复时,`.snyk`、`.semgrepignore`、`.trivyignore`、`.dvalincodeignore` 会恢复成 base 版本,
|
|
136
|
+
新增的行内标记(`deepcode ignore`、`nosemgrep`、`nosec`、`NOSONAR` 等)会被抹掉 ——
|
|
137
|
+
被"静音"而不是被修复的问题仍然会让这次修复失败。忽略是人在单独变更里做的风险决定,从来不是修复。
|
|
138
|
+
|
|
139
|
+
凡是 Dvalin 说"已验证"的地方,判定标准都一样:修复循环、`dvalin verify`、MCP 的 `dvalin_verify_findings`、
|
|
140
|
+
单轮 `--fix --verify`,以及 CI 的 `reverify`。这些入口签发的是 `dvalin-fix-record/v3` 记录,
|
|
141
|
+
它还会拒绝"把问题藏起来而不是修掉"的改动 —— 换成同类危险调用、删掉有漏洞的文件、删测试或删断言。
|
|
142
|
+
在非 git 仓库中无法确定改动范围,记录保持 v2,并写明未评估规避。
|
|
143
|
+
|
|
144
|
+
### 让它一直修到门禁会通过为止
|
|
145
|
+
|
|
146
|
+
```sh
|
|
147
|
+
dvalincode dvalin . --scanners builtin,snyk-code,snyk-oss --until-clean --max-rounds 3 --executor codex
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
`--until-clean` 把一次修复变成有上限的循环:执行器改代码,Dvalin 用同样的引擎重新扫描、亲自跑项目检查,
|
|
151
|
+
然后**只把还没解决的部分**发回给执行器 —— 仍存在的目标、它的改动新引入的问题、失败的检查及其最后几行输出、
|
|
152
|
+
它新增的忽略 —— 让它再修一轮。依赖漏洞优先处理。
|
|
153
|
+
|
|
154
|
+
循环会在以下情况停下并说明原因:所有目标消失、没有新引入阻断问题、检查全部通过(`verified`);轮数用完;
|
|
155
|
+
某一轮留下完全相同的问题、或问题集合不再缩小(`stalled`);目标需要人处理,比如依赖没有可修复版本
|
|
156
|
+
(`not-auto-fixable`);引擎或检查跑不起来(`unverifiable`)。执行器新增的忽略会在每次扫描前被撤销,
|
|
157
|
+
并且在被删除之前一直算作未解决的问题。每种结局都会签发修复记录,每一轮都记录在
|
|
158
|
+
`~/.dvalincode/security/fix-loops/` 下。
|
|
159
|
+
|
|
160
|
+
每一轮会尽量短,但判定方式不变。各扫描引擎并行运行,一次扫描的耗时取决于最慢的引擎,而不是所有引擎之和。
|
|
161
|
+
在两轮之间,逐文件分析的引擎(Dvalin Built-in、Semgrep)只重扫本次改动的文件和目标所在的文件,
|
|
162
|
+
其他引擎始终扫描整个目录树。这种缩小范围的扫描只用于给执行器反馈:任何会让循环停下的一轮,
|
|
163
|
+
都会在同一棵树上用全量扫描重新判定,最终结论和修复记录只来自全量扫描。
|
|
164
|
+
`--full-rescan` 让每一轮都做全量扫描;`dvalin loop-stats` 会报告每轮扫描耗时,以及全量扫描改变判定的次数。
|
|
165
|
+
|
|
166
|
+
对**代码类**问题,循环会先要求复现:执行器只写测试,Dvalin 在未修复的代码上运行,并要求它失败 ——
|
|
167
|
+
必须是断言失败,而不是测试运行器缺失、或引用了还没写的函数。测试文件会被记录哈希;修复必须让它们在
|
|
168
|
+
**不被改动**的前提下通过,这次运行会作为一项检查写进记录。如果没有任何测试能复现,循环在动手修之前就以
|
|
169
|
+
`not-reproduced` 停下:这可能是误报,交给人来判断。测试运行器自动推断(vitest、jest、mocha、`node --test`、
|
|
170
|
+
pytest、`go test`),也可以用 `--repro-command 'npx vitest run {files}'` 或 `dvalin.security.json` 里的
|
|
171
|
+
`reproduce` 指定 —— 永远不由执行器选择。
|
|
172
|
+
|
|
173
|
+
每一轮修复还会拒绝 agent 在"让扫描器闭嘴"目标下常用的规避手法:把危险调用换成同类写法(`eval` →
|
|
174
|
+
`new Function`,`exec` → 带 `shell: true` 的 `spawn`)、删掉有漏洞的文件、删测试、删断言。
|
|
175
|
+
实际上第一种手法单靠扫描器是拦不住的 —— 规则不再匹配 —— 真正拦住它的是复现测试和规避检测。
|
|
176
|
+
|
|
177
|
+
### 始终基于最新的 main,并在 CI 里收尾
|
|
178
|
+
|
|
179
|
+
```sh
|
|
180
|
+
dvalincode dvalin . --scanners builtin,snyk-code,snyk-oss --until-clean \
|
|
181
|
+
--rebase-onto origin/main --executor codex --draft-pr --sign-key ci.key
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
加上 `--rebase-onto` 后,循环会在开始前和每一轮之后拉取上游并把修复 rebase 上去,然后在新的 base 上评判。
|
|
185
|
+
冲突交给执行器 —— 只给冲突文件,并要求"不要运行 git" —— rebase 由 Dvalin 自己继续;文件里残留冲突标记就算没解决。
|
|
186
|
+
解决不了就中止 rebase,工作区恢复原样,循环以 `rebase-conflict` 停下。每次 rebase 后都会在新 base 上重新扫描建立基线,
|
|
187
|
+
队友合进 main 的问题不会被算到这次修复头上。
|
|
188
|
+
|
|
189
|
+
`--draft-pr` 会把记录提交到 `.dvalin/fix-record.json`,
|
|
190
|
+
[`docs/examples/dvalin-fix-loop.yml`](docs/examples/dvalin-fix-loop.yml) 在 PR 上用 `reverify: true` 重新执行:
|
|
191
|
+
重新扫描 base 和 head、重跑检查,并在原地还原修复后重跑复现测试(必须失败)、恢复后再跑(必须通过)—— 最后用 CI 密钥签名。
|
|
192
|
+
|
|
83
193
|
要建立“禁止新增高风险问题”的增量门禁,把策略和基线一并提交到仓库:
|
|
84
194
|
|
|
85
195
|
```sh
|
|
@@ -103,7 +213,7 @@ steps:
|
|
|
103
213
|
- uses: actions/checkout@v5
|
|
104
214
|
with:
|
|
105
215
|
fetch-depth: 0 # 让扫描能取到 base commit
|
|
106
|
-
- uses: arthurpanhku/dvalincode@v0.
|
|
216
|
+
- uses: arthurpanhku/dvalincode@v0.21.0
|
|
107
217
|
with:
|
|
108
218
|
fail-on: high
|
|
109
219
|
diff: true # 只报告这个 PR 改动的部分
|
|
@@ -126,14 +236,17 @@ steps:
|
|
|
126
236
|
如果你的流水线产出了 fix record,把它交给同一个 action:
|
|
127
237
|
|
|
128
238
|
```yaml
|
|
129
|
-
- uses: arthurpanhku/dvalincode@v0.
|
|
239
|
+
- uses: arthurpanhku/dvalincode@v0.21.0
|
|
130
240
|
with:
|
|
131
241
|
fix-record: fix-record.json
|
|
132
242
|
```
|
|
133
243
|
|
|
134
244
|
runner 会仅凭这个文件本身重新推导它 —— 重算哈希,并从它自己的证据重新推出结论 ——
|
|
135
245
|
然后把结果发到 PR 上。一份签发之后被改过的记录会在这里失败,并让整个 job 失败。
|
|
136
|
-
|
|
246
|
+
|
|
247
|
+
重新推导只能证明记录**自洽**,证明不了它出自真正跑过验证的人:记录里的每个字段(包括退出码)
|
|
248
|
+
伪造者都能写出来,一份自洽的伪造记录照样能通过重新推导。要补上这个缺口,需要两件事 ——
|
|
249
|
+
在 runner 上重新执行这份声明,并对 runner 观察到的结果签名。
|
|
137
250
|
|
|
138
251
|
```
|
|
139
252
|
🔏 Verified Fix Record
|
|
@@ -156,6 +269,45 @@ runner 会仅凭这个文件本身重新推导它 —— 重算哈希,并从
|
|
|
156
269
|
- outcome: regressed
|
|
157
270
|
```
|
|
158
271
|
|
|
272
|
+
### 在 runner 上重新执行,并对看到的结果签名
|
|
273
|
+
|
|
274
|
+
```yaml
|
|
275
|
+
- uses: actions/checkout@v5
|
|
276
|
+
with:
|
|
277
|
+
fetch-depth: 0 # 需要能拿到 base commit
|
|
278
|
+
- run: npm ci # 项目自己的检查会在 runner 上执行
|
|
279
|
+
- uses: arthurpanhku/dvalincode@v0.22.0 # reverify 随 v0.22.0 发布;打 tag 之前请固定到 main 的某个 commit SHA
|
|
280
|
+
with:
|
|
281
|
+
fix-record: fix-record.json
|
|
282
|
+
reverify: true
|
|
283
|
+
signing-key: ${{ secrets.DVALIN_SIGNING_KEY }} # 可选
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
开启 `reverify: true` 后,被声明的记录只提供两样东西:它说修了**哪些 target**,以及
|
|
287
|
+
**谁**是执行者。其余一切都重新观察:
|
|
288
|
+
|
|
289
|
+
- 检出并扫描 **base** commit,每个被声明的 target 必须真的在那里存在 —— 记录不能把
|
|
290
|
+
"删掉一个从未存在的 finding" 算作功劳;
|
|
291
|
+
- 扫描 **head**,"已消失" 由 runner 亲眼观察;
|
|
292
|
+
- 在 runner 上运行项目检查,检查项、门禁和扫描器都读自 **base** commit 的
|
|
293
|
+
`dvalin.security.json` —— 一个放宽自己门禁或删掉自己检查的 PR,仍按它想改掉的规则评判;
|
|
294
|
+
- 根据这些观察签发一份全新的记录,只有它判定通过,job 才通过。
|
|
295
|
+
|
|
296
|
+
提供 `signing-key` 时,新记录会被签名(Ed25519,签的是记录哈希)。私钥在项目检查运行前
|
|
297
|
+
就被读入内存并从环境变量中移除,被审查的代码读不到它。下游(发布 job、其他仓库、审计方)
|
|
298
|
+
就可以要求这个签名:
|
|
299
|
+
|
|
300
|
+
```sh
|
|
301
|
+
dvalin keygen --out ci # 只需一次;ci.key 存为 secret,ci.pub 公开
|
|
302
|
+
dvalin verify-fix record.json --trusted-key ci.pub
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
在 `--trusted-key` 下,未签名或只由你没指定的密钥签名的记录都会失败。有效签名只说明
|
|
306
|
+
**哪个密钥为这份记录背书**;是否信任这个密钥由你决定 —— 信任 CI 密钥的理由,是 CI job
|
|
307
|
+
亲自重新执行了验证,而不是照抄。本地可以用 `dvalin reverify <record> --base origin/main`
|
|
308
|
+
做同样的重新执行,用 `dvalin sign-fix` 给一份能重新推导的记录签名。
|
|
309
|
+
[FVP-1 §4a、§5a →](docs/spec/FIX-VERIFICATION.md)
|
|
310
|
+
|
|
159
311
|
### 或者让你的 agent 调用它
|
|
160
312
|
|
|
161
313
|
如果代码是 agent 写的,那检查它的就不能是同一个 agent。DvalinCode 本身是个 MCP
|
|
@@ -206,6 +358,8 @@ Codex 会采纳扫描工具的只读 MCP 标注;Claude Code 按其安全设计
|
|
|
206
358
|
| **Windsurf · Zed** | 在各自设置里配 stdio MCP —— [server 命令](integrations/mcp/) |
|
|
207
359
|
| **任意 MCP 客户端** | [MCP registry](https://registry.modelcontextprotocol.io/):`io.github.arthurpanhku/dvalincode` |
|
|
208
360
|
| **GitHub Actions** | [Marketplace action](https://github.com/marketplace/actions/dvalin-security-scan) —— 结果直接标在 PR diff 上 |
|
|
361
|
+
| **GitLab CI** | `dvalin init --ci gitlab` —— 新增 finding 卡住 MR,并显示在 Code Quality 面板里 |
|
|
362
|
+
| **pre-commit** | [`dvalin-scan` hook](.pre-commit-hooks.yaml) —— 每次提交前跑同一套策略门禁 |
|
|
209
363
|
| **任意 CI** | `dvalin scan . --fail-on high`,输出 SARIF 供 code scanning 用 |
|
|
210
364
|
|
|
211
365
|
各家的 MCP 配置格式并不通用——VS Code 的 key 是 `servers`,Cursor 是 `mcpServers`,
|
|
@@ -303,7 +457,8 @@ Dvalin 在这四处背后是同一个 MCP server、同一次确定性扫描 —
|
|
|
303
457
|
| **回头读代码** | VS Code | `mcp-install vscode` · [扩展](editors/vscode/):Problems、覆盖度与门禁状态 | ✅ 编辑器内已验证 |
|
|
304
458
|
| **卡住合并** | GitHub Actions | [Marketplace action](https://github.com/marketplace/actions/dvalin-security-scan) —— finding 落在 diff 上,fix record 在 runner 上重新推导 | ✅ 本仓库自己的 CI 就在跑 |
|
|
305
459
|
| | 任意 CI | `dvalin scan . --fail-on high`,输出 SARIF | ✅ 退出码就是契约 |
|
|
306
|
-
| **相信这个结论** | 任何人,离线 | `dvalin verify-fix record.json` | ✅ 不需要 workspace、网络或任何 Dvalin 状态 |
|
|
460
|
+
| **相信这个结论** | 任何人,离线 | `dvalin verify-fix record.json --trusted-key ci.pub` | ✅ 不需要 workspace、网络或任何 Dvalin 状态 |
|
|
461
|
+
| | 合并门禁 | `reverify: true` —— base 与 head 重新扫描、检查在 runner 上重跑、新记录签名 | ✅ 有测试覆盖 |
|
|
307
462
|
|
|
308
463
|
**✅** 表示真实客户端被端到端驱动过,并且观察到了工具调用。
|
|
309
464
|
**⚙️** 表示配置能生成、格式经过测试,但还没有抓到会话记录。这个区别这里不含糊过去 ——
|
|
@@ -1040,6 +1195,7 @@ prompt、UI 文案、工具 schema、模块布局和产品实现均为原创;
|
|
|
1040
1195
|
| badhope | [@weed33834](https://github.com/weed33834) |
|
|
1041
1196
|
| Samran Asif | [@webdevsamran](https://github.com/webdevsamran) |
|
|
1042
1197
|
| dchaudhari7177 | [@dchaudhari7177](https://github.com/dchaudhari7177) |
|
|
1198
|
+
| TayfurYldz | [@TayfurYldz](https://github.com/TayfurYldz) |
|
|
1043
1199
|
|
|
1044
1200
|
查看[完整贡献记录](https://github.com/arthurpanhku/dvalincode/graphs/contributors),其中也包含自动依赖更新和维护记录。
|
|
1045
1201
|
|
package/dist/agent/compact.d.ts
CHANGED
|
@@ -4,3 +4,11 @@ export declare function estimateTokens(messages: ChatMessage[]): number;
|
|
|
4
4
|
export declare function estimateRequestTokens(messages: ChatMessage[], systemPrompt: string, tools?: ToolDef[]): number;
|
|
5
5
|
export declare function summarizeWithLLM(messages: ChatMessage[], provider: ProviderAdapter, runtime?: ChatRequest['runtime'], signal?: AbortSignal): Promise<string>;
|
|
6
6
|
export declare function buildCompactedHistory(summary: string): ChatMessage[];
|
|
7
|
+
export declare function summaryMessage(summary: string): ChatMessage;
|
|
8
|
+
/** The task message kept verbatim when a turn is compacted mid-way. */
|
|
9
|
+
export declare function compactedTaskMessage(task: string): ChatMessage;
|
|
10
|
+
/**
|
|
11
|
+
* The latest messages that fit in `budget` tokens, starting at an assistant
|
|
12
|
+
* message so that no tool result is kept without the call it answers.
|
|
13
|
+
*/
|
|
14
|
+
export declare function recentTail(messages: ChatMessage[], budget: number): ChatMessage[];
|
package/dist/agent/compact.js
CHANGED
|
@@ -1,10 +1,23 @@
|
|
|
1
1
|
export function estimateTokens(messages) {
|
|
2
|
-
const total = messages.reduce((acc, m) => acc + (m.content
|
|
3
|
-
return Math.ceil(total
|
|
2
|
+
const total = messages.reduce((acc, m) => acc + roughTokens(m.content ?? '') + roughTokens(JSON.stringify(m.tool_calls ?? [])), 0);
|
|
3
|
+
return Math.ceil(total);
|
|
4
4
|
}
|
|
5
5
|
/** Estimate the complete provider request, not just visible chat content. */
|
|
6
6
|
export function estimateRequestTokens(messages, systemPrompt, tools = []) {
|
|
7
|
-
return estimateTokens(messages) + Math.ceil((systemPrompt
|
|
7
|
+
return estimateTokens(messages) + Math.ceil(roughTokens(systemPrompt) + roughTokens(JSON.stringify(tools)));
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* About four ASCII characters per token, but roughly one token per CJK (or
|
|
11
|
+
* other non-ASCII) character -- counting those at a quarter too would
|
|
12
|
+
* underestimate a Chinese conversation about fourfold.
|
|
13
|
+
*/
|
|
14
|
+
function roughTokens(text) {
|
|
15
|
+
let nonAscii = 0;
|
|
16
|
+
for (let i = 0; i < text.length; i++) {
|
|
17
|
+
if (text.charCodeAt(i) > 0x7f)
|
|
18
|
+
nonAscii++;
|
|
19
|
+
}
|
|
20
|
+
return (text.length - nonAscii) / 4 + nonAscii;
|
|
8
21
|
}
|
|
9
22
|
const COMPACT_PROMPT = `Summarize this coding session using exactly this format:
|
|
10
23
|
|
|
@@ -25,7 +38,7 @@ export async function summarizeWithLLM(messages, provider, runtime, signal) {
|
|
|
25
38
|
const transcript = compactTranscript(messages);
|
|
26
39
|
const resp = await provider.chat({
|
|
27
40
|
messages: [{ role: 'user', content: `${COMPACT_PROMPT}\n\n---\n${transcript}` }],
|
|
28
|
-
maxTokens:
|
|
41
|
+
maxTokens: 1_500,
|
|
29
42
|
temperature: 0.3,
|
|
30
43
|
runtime,
|
|
31
44
|
signal,
|
|
@@ -66,9 +79,35 @@ function compactTranscript(messages, maxChars = 64_000) {
|
|
|
66
79
|
}
|
|
67
80
|
export function buildCompactedHistory(summary) {
|
|
68
81
|
return [
|
|
69
|
-
|
|
82
|
+
summaryMessage(summary),
|
|
70
83
|
{ role: 'user', content: 'Context was compacted. Continue from the Pending list.' },
|
|
71
84
|
{ role: 'assistant', content: 'Understood. I have the session summary and am ready to continue.' },
|
|
72
85
|
];
|
|
73
86
|
}
|
|
87
|
+
export function summaryMessage(summary) {
|
|
88
|
+
return { role: 'system', content: `[Conversation summary]\n\n${summary}` };
|
|
89
|
+
}
|
|
90
|
+
/** The task message kept verbatim when a turn is compacted mid-way. */
|
|
91
|
+
export function compactedTaskMessage(task) {
|
|
92
|
+
return {
|
|
93
|
+
role: 'user',
|
|
94
|
+
content: `${task}\n\n[Context was compacted: the summary above covers the earlier work on this task. Continue from where it left off.]`,
|
|
95
|
+
};
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* The latest messages that fit in `budget` tokens, starting at an assistant
|
|
99
|
+
* message so that no tool result is kept without the call it answers.
|
|
100
|
+
*/
|
|
101
|
+
export function recentTail(messages, budget) {
|
|
102
|
+
let start = messages.length;
|
|
103
|
+
let used = 0;
|
|
104
|
+
for (let i = messages.length - 1; i >= 0; i--) {
|
|
105
|
+
used += estimateTokens([messages[i]]);
|
|
106
|
+
if (used > budget)
|
|
107
|
+
break;
|
|
108
|
+
if (messages[i].role === 'assistant')
|
|
109
|
+
start = i;
|
|
110
|
+
}
|
|
111
|
+
return messages.slice(start);
|
|
112
|
+
}
|
|
74
113
|
//# sourceMappingURL=compact.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"compact.js","sourceRoot":"","sources":["../../src/agent/compact.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,cAAc,CAAC,QAAuB;IACpD,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAC3B,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,
|
|
1
|
+
{"version":3,"file":"compact.js","sourceRoot":"","sources":["../../src/agent/compact.ts"],"names":[],"mappings":"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"}
|
package/dist/agent/loop.d.ts
CHANGED
|
@@ -48,5 +48,10 @@ export declare class AgentLoop {
|
|
|
48
48
|
processMessage(userMessage: string, history: ChatMessage[], onEvent?: AgentEventHandler, signal?: AbortSignal): Promise<LoopResult>;
|
|
49
49
|
/** Emit the terminal run_end event, folding in any best-effort write warnings. */
|
|
50
50
|
private finishRun;
|
|
51
|
+
/**
|
|
52
|
+
* Summarize `messages`. With `keep` (a compaction in the middle of a turn) the
|
|
53
|
+
* summary is followed by those messages verbatim, instead of the generic
|
|
54
|
+
* continuation used between turns.
|
|
55
|
+
*/
|
|
51
56
|
private handleCompact;
|
|
52
57
|
}
|