dsh-boost 0.1.2 → 0.1.4
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.en.md +157 -80
- package/README.md +119 -65
- package/dist/admission/usage.js +52 -8
- package/dist/admission/usage.js.map +1 -1
- package/dist/hooks/llm-stream.js +121 -5
- package/dist/hooks/llm-stream.js.map +1 -1
- package/dist/hooks/post-execute.js +129 -31
- package/dist/hooks/post-execute.js.map +1 -1
- package/dist/index.js +230 -5
- package/dist/index.js.map +1 -1
- package/dist/projection/apply.js +11 -2
- package/dist/projection/apply.js.map +1 -1
- package/dist/projection/truncate.js +27 -10
- package/dist/projection/truncate.js.map +1 -1
- package/dist/tools/boost.js +82 -2
- package/dist/tools/boost.js.map +1 -1
- package/package.json +4 -3
|
@@ -8,16 +8,18 @@
|
|
|
8
8
|
* - `tools/post-execute` first gates on the same cached scope judgement the
|
|
9
9
|
* protocol section reads, then canonicalises the result and runs a
|
|
10
10
|
* conservative invalidation check. It files the arriving receipt under
|
|
11
|
-
* `'root'`,
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
11
|
+
* `'root'`, then — only when the decision leaves that receipt visible
|
|
12
|
+
* (`projectionTargetOf`) — works the substitution decision (`decide` →
|
|
13
|
+
* admission → pending queue / shadow receipt / fallback), then the
|
|
14
|
+
* double-projection guard, and finally projects the receipt when the scope
|
|
15
|
+
* document asks for it. Order is fixed: `next() → scope gate → canonicalise
|
|
16
|
+
* → invalidate → visibility gate → decide → (shadow receipt | admit and
|
|
17
|
+
* enqueue | fallback) → double-projection guard → projection → return the
|
|
18
|
+
* decision` (plan §Task 23b). A call with no `exec.agent` is not the
|
|
19
|
+
* plugin's to inspect: the downstream decision is returned untouched and a
|
|
20
|
+
* `skip:no-scope` receipt keeps the pass visible (design §5.5). A call
|
|
21
|
+
* carrying `exec.parent` is a PTC inner dispatch and returns before any of
|
|
22
|
+
* this: it is not the step's root receipt.
|
|
21
23
|
* - `llm/stream` is the model-request waterfall. Its body lives in
|
|
22
24
|
* `./llm-stream.ts` (Task 23c-1) and is re-exported below: it lets the
|
|
23
25
|
* plugin's own selector request through untouched, then answers a pending
|
|
@@ -117,6 +119,9 @@ const SELECTOR_RECEIPT_MAX_CHARS = 1_200;
|
|
|
117
119
|
/** Skip reasons that mean the projection machinery degraded, not "nothing to cut". */
|
|
118
120
|
const PROJECTION_DEGRADATIONS = new Set([
|
|
119
121
|
'no-spill',
|
|
122
|
+
// `no-owner` is emitted by `projectApply`'s direct-call contract, not by this
|
|
123
|
+
// hook (design §5.4): the hook only calls it once an owner is known. Kept so
|
|
124
|
+
// a future caller cannot silently lose the mapping.
|
|
120
125
|
'no-owner',
|
|
121
126
|
'projection-skipped:no-footer',
|
|
122
127
|
'spill-failed',
|
|
@@ -204,10 +209,8 @@ function pendingAnchorsOf(deps, sessionId) {
|
|
|
204
209
|
* (`llm/stream`, 23c), where the compared text is the anchored receipt's current
|
|
205
210
|
* body in the outgoing messages.
|
|
206
211
|
*/
|
|
207
|
-
function markerResetOf(
|
|
212
|
+
function markerResetOf(receiptText) {
|
|
208
213
|
try {
|
|
209
|
-
if (pending == null)
|
|
210
|
-
return undefined;
|
|
211
214
|
return looksPruned(receiptText) ? 'pruned-reset' : undefined;
|
|
212
215
|
}
|
|
213
216
|
catch {
|
|
@@ -613,23 +616,25 @@ async function recordProjectionRetrieval(deps, exec, sessionId, pending, visible
|
|
|
613
616
|
// Admission and the decision branch
|
|
614
617
|
// ---------------------------------------------------------------------------
|
|
615
618
|
/**
|
|
616
|
-
* The
|
|
617
|
-
*
|
|
619
|
+
* The saving of skipping one model step: the last real request's `totalTokens`
|
|
620
|
+
* (`input + cacheRead + output`), which is what design §5.3 defines it as.
|
|
618
621
|
*
|
|
619
|
-
*
|
|
620
|
-
*
|
|
621
|
-
*
|
|
622
|
-
*
|
|
622
|
+
* All three parts are skipped when the model does not run: the replayed context
|
|
623
|
+
* is not sent and the response is not generated. The context only grows as
|
|
624
|
+
* receipts enter it, so the last request is a lower bound. A missing ledger or
|
|
625
|
+
* sample is 0, never an interpolation, so admission falls back to the model when
|
|
626
|
+
* it cannot measure (design §5.3: measured, not estimated).
|
|
623
627
|
*/
|
|
624
628
|
function savedTokensOf(deps, sessionId) {
|
|
625
629
|
try {
|
|
626
630
|
const last = sessionUsage(deps, sessionId)?.last();
|
|
627
631
|
if (last === undefined)
|
|
628
632
|
return 0;
|
|
629
|
-
const { input, cacheRead } = last;
|
|
630
|
-
|
|
633
|
+
const { input, cacheRead, output } = last;
|
|
634
|
+
const parts = [input, cacheRead, output];
|
|
635
|
+
if (parts.some((part) => !Number.isFinite(part) || part < 0))
|
|
631
636
|
return 0;
|
|
632
|
-
const total = input + cacheRead;
|
|
637
|
+
const total = input + cacheRead + output;
|
|
633
638
|
return Number.isFinite(total) ? total : 0;
|
|
634
639
|
}
|
|
635
640
|
catch {
|
|
@@ -839,6 +844,10 @@ async function settleRollover(deps, sessionId, turn) {
|
|
|
839
844
|
candidateId,
|
|
840
845
|
...(dispatched.evidence ?? {}),
|
|
841
846
|
saved_input_tokens: settled.saved_input_tokens,
|
|
847
|
+
// Row 7: the same pair of samples also yields the lower estimate; the
|
|
848
|
+
// settled line is the only place a measured saving exists, so both numbers
|
|
849
|
+
// travel together.
|
|
850
|
+
avoided_total_tokens: settled.avoided_total_tokens,
|
|
842
851
|
cache_hit_delta: settled.cache_hit_delta,
|
|
843
852
|
output_tokens: settled.output_tokens,
|
|
844
853
|
});
|
|
@@ -1113,6 +1122,29 @@ function admissionViewOf(exec) {
|
|
|
1113
1122
|
return undefined;
|
|
1114
1123
|
}
|
|
1115
1124
|
}
|
|
1125
|
+
/**
|
|
1126
|
+
* The args as they will arrive from the host.
|
|
1127
|
+
*
|
|
1128
|
+
* `JSON.stringify` collapses `-0` to `0` and rewrites non-finite numbers to
|
|
1129
|
+
* `null`, so a pending tree that skipped this round trip would disagree with
|
|
1130
|
+
* its own dispatched call: `sameLiteral` would report tampering and the planned
|
|
1131
|
+
* call would never run (review cod#2).
|
|
1132
|
+
*/
|
|
1133
|
+
function jsonNormalise(args) {
|
|
1134
|
+
try {
|
|
1135
|
+
const text = JSON.stringify(args);
|
|
1136
|
+
if (text === undefined)
|
|
1137
|
+
return args;
|
|
1138
|
+
const parsed = JSON.parse(text);
|
|
1139
|
+
if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
|
|
1140
|
+
return parsed;
|
|
1141
|
+
}
|
|
1142
|
+
return args;
|
|
1143
|
+
}
|
|
1144
|
+
catch {
|
|
1145
|
+
return args;
|
|
1146
|
+
}
|
|
1147
|
+
}
|
|
1116
1148
|
/**
|
|
1117
1149
|
* The substitution decision and its side effects.
|
|
1118
1150
|
*
|
|
@@ -1196,6 +1228,10 @@ async function decideSubstitution(deps, ctx) {
|
|
|
1196
1228
|
});
|
|
1197
1229
|
}
|
|
1198
1230
|
catch {
|
|
1231
|
+
// A throwing gate silently disabled substitution for this receipt, so make
|
|
1232
|
+
// it visible in `status.counts` (review row 24). The plan was already
|
|
1233
|
+
// consumed above; nothing can fire later from this failure.
|
|
1234
|
+
await appendReceipt(deps, ledgerEntry(ctx, 'skip', 'substitute-skipped:gate-error', { stepId: 'root' }));
|
|
1199
1235
|
return;
|
|
1200
1236
|
}
|
|
1201
1237
|
// Substitution synthesises a dispatch and expects POSIX process semantics;
|
|
@@ -1325,8 +1361,14 @@ async function decideSubstitution(deps, ctx) {
|
|
|
1325
1361
|
candidateId,
|
|
1326
1362
|
// The candidate's tool name identifies the call; the executable args are
|
|
1327
1363
|
// the *decision's* bound tree, never the plan's `$public` template.
|
|
1364
|
+
//
|
|
1365
|
+
// Normalised through a JSON round trip so the pending tree is byte-for-byte
|
|
1366
|
+
// what the host will hand back. `JSON.stringify` rewrites `-0` to `0` and
|
|
1367
|
+
// `Infinity`/`NaN` to `null`; without this, a legal plan arg of `-0` would
|
|
1368
|
+
// arrive as `0` and `sameLiteral` would report tampering, so the planned
|
|
1369
|
+
// call would never run (review cod#2).
|
|
1328
1370
|
name: candidate.tool,
|
|
1329
|
-
args: boundArgs,
|
|
1371
|
+
args: jsonNormalise(boundArgs),
|
|
1330
1372
|
turn: ctx.turn,
|
|
1331
1373
|
step,
|
|
1332
1374
|
// The plan is one-shot (cleared above), so the evidence must travel with
|
|
@@ -1582,6 +1624,13 @@ async function projectDecision(deps, receipt, decision, ctx) {
|
|
|
1582
1624
|
before,
|
|
1583
1625
|
after,
|
|
1584
1626
|
saved_projection_tokens: before - after,
|
|
1627
|
+
// How much the projection cut, in the units the footer names. Without
|
|
1628
|
+
// it a reader of the ledger cannot tell a 2 KB cut from a 200 KB one
|
|
1629
|
+
// (review cod#3: these fields had no consumer).
|
|
1630
|
+
...(outcome.omittedBytes === undefined ? {} : { omitted_bytes: outcome.omittedBytes }),
|
|
1631
|
+
...(outcome.omittedCodePoints === undefined
|
|
1632
|
+
? {}
|
|
1633
|
+
: { omitted_code_points: outcome.omittedCodePoints }),
|
|
1585
1634
|
estimate: deps.estimateKind ?? 'unknown',
|
|
1586
1635
|
}));
|
|
1587
1636
|
}
|
|
@@ -1590,6 +1639,10 @@ async function projectDecision(deps, receipt, decision, ctx) {
|
|
|
1590
1639
|
unit: 'raw',
|
|
1591
1640
|
horizon_steps: projectionHorizonOf(deps, ctx.sessionId),
|
|
1592
1641
|
...(ctx.retrievalCall === true ? { call_was_retrieval: true } : {}),
|
|
1642
|
+
...(outcome.omittedBytes === undefined ? {} : { omitted_bytes: outcome.omittedBytes }),
|
|
1643
|
+
...(outcome.omittedCodePoints === undefined
|
|
1644
|
+
? {}
|
|
1645
|
+
: { omitted_code_points: outcome.omittedCodePoints }),
|
|
1593
1646
|
estimate: 'unknown',
|
|
1594
1647
|
}));
|
|
1595
1648
|
}
|
|
@@ -1623,15 +1676,45 @@ async function projectDecision(deps, receipt, decision, ctx) {
|
|
|
1623
1676
|
* The decision + projection stage.
|
|
1624
1677
|
*
|
|
1625
1678
|
* Both seams live in one place so the listener's order is visible in one
|
|
1626
|
-
* function:
|
|
1627
|
-
*
|
|
1628
|
-
* (design §5.2-5), and in
|
|
1629
|
-
* its accounting line.
|
|
1679
|
+
* function: the receipt-visibility gate, then decide, then the
|
|
1680
|
+
* double-projection guard, then project. A shadow substitution does not stop
|
|
1681
|
+
* the projection: the two switches are independent (design §5.2-5), and in
|
|
1682
|
+
* projection-shadow mode the projection writes only its accounting line.
|
|
1630
1683
|
*/
|
|
1631
1684
|
async function applyDecision(deps, decision, ctx) {
|
|
1685
|
+
// Substitution is only legitimate while the receipt is what the model sees.
|
|
1686
|
+
// `decide` and its guards were evaluated against `ctx.receipt.text`; a
|
|
1687
|
+
// `block`, or an `accept` carrying a replacement `value`, hides that text, so
|
|
1688
|
+
// a commit would dispatch a call whose evidence the model never received
|
|
1689
|
+
// (review row 11). `projectionTargetOf` is the same visibility predicate
|
|
1690
|
+
// projection uses: it rejects `block` and any `accept` with a `value`, and
|
|
1691
|
+
// accepts an `accept` whose content is text (possibly rewritten).
|
|
1692
|
+
//
|
|
1693
|
+
// A hidden receipt still consumes the one-shot plan: the plan was written for
|
|
1694
|
+
// the call that produced it, and keeping it would let it fire against a later
|
|
1695
|
+
// receipt whose text it was not written for.
|
|
1696
|
+
//
|
|
1632
1697
|
// Projection below runs for a shadow commit too: the decision side never
|
|
1633
1698
|
// suppresses the projection ledger.
|
|
1634
|
-
|
|
1699
|
+
const visible = projectionTargetOf(decision, ctx.receipt, ctx.result);
|
|
1700
|
+
if (visible === undefined) {
|
|
1701
|
+
clearPlan(deps, ctx.sessionId);
|
|
1702
|
+
}
|
|
1703
|
+
else if (visible !== ctx.receipt.text) {
|
|
1704
|
+
// An `accept` carrying its own `content` shows the model text the plugin
|
|
1705
|
+
// never canonicalised, so every guard and every literal in the plan was
|
|
1706
|
+
// checked against something else. Projection may still run — it rewrites
|
|
1707
|
+
// the visible text deliberately — but a substitution must not commit on
|
|
1708
|
+
// evidence the model cannot see (review qr5#3).
|
|
1709
|
+
//
|
|
1710
|
+
// No receipt: this is the normal outer-shaper path (`dsh-spill-policy`
|
|
1711
|
+
// appends its footer in every session), not a degradation. A receipt here
|
|
1712
|
+
// would be one line per oversized receipt and would read as a failure.
|
|
1713
|
+
clearPlan(deps, ctx.sessionId);
|
|
1714
|
+
}
|
|
1715
|
+
else {
|
|
1716
|
+
await decideSubstitution(deps, ctx);
|
|
1717
|
+
}
|
|
1635
1718
|
// Second-projection guard. Two host shapers are outer to this listener:
|
|
1636
1719
|
//
|
|
1637
1720
|
// - The spill policy registers with `{ prepend: true }`: it calls `next()`
|
|
@@ -1650,8 +1733,23 @@ async function applyDecision(deps, decision, ctx) {
|
|
|
1650
1733
|
// to a receipt this listener already clipped. A family the plugin does not
|
|
1651
1734
|
// project leaves the host shaper untouched.
|
|
1652
1735
|
//
|
|
1653
|
-
//
|
|
1654
|
-
//
|
|
1736
|
+
// What these two checks can and cannot catch (review row 25):
|
|
1737
|
+
//
|
|
1738
|
+
// - The first reads `ctx.receipt.text`, captured before this listener
|
|
1739
|
+
// returns. The outer spill policy appends its footer to the decision
|
|
1740
|
+
// *after* this point, so this check can never see the host's own footer.
|
|
1741
|
+
// It can only fire when the tool's output already ends in a spill notice —
|
|
1742
|
+
// for example a `read` of a spill artifact, whose text carries the notice
|
|
1743
|
+
// literally. That is still a receipt that is already a preview, so
|
|
1744
|
+
// refusing to project it again is the intended, if narrow, guard.
|
|
1745
|
+
// - The second sees a replacement an inner listener wrote into the decision.
|
|
1746
|
+
// An outer shaper's footer is invisible to it too.
|
|
1747
|
+
//
|
|
1748
|
+
// Neither check is full double-spill detection: at this point the host's
|
|
1749
|
+
// footer does not exist yet, so projection and the outer spill policy can
|
|
1750
|
+
// both act on one receipt. That is fail-safe, not prevention: the
|
|
1751
|
+
// projection's own footer keeps the original retrievable, and the host's
|
|
1752
|
+
// second notice points at the projected text.
|
|
1655
1753
|
if (await isAlreadySpilled(deps, ctx.receipt.text))
|
|
1656
1754
|
return decision;
|
|
1657
1755
|
const downstreamText = decisionTextOf(decision) ?? ctx.receipt.text;
|
|
@@ -1787,7 +1885,7 @@ async function postExecute(deps, state, exec, result, next) {
|
|
|
1787
1885
|
// `!= null` rather than `!== undefined`: a foreign store can hand back a
|
|
1788
1886
|
// null, and dereferencing it would throw out of the hook.
|
|
1789
1887
|
if (pending != null) {
|
|
1790
|
-
const reset = markerResetOf(
|
|
1888
|
+
const reset = markerResetOf(receipt.text);
|
|
1791
1889
|
if (reset !== undefined) {
|
|
1792
1890
|
await resetInvalidatedPending(deps, exec, sessionId, turn, pending, reset);
|
|
1793
1891
|
if (retrieval !== undefined) {
|