dsh-boost 0.0.0-stage → 0.1.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.
Files changed (110) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +29 -0
  3. package/README.en.md +476 -0
  4. package/README.md +408 -2
  5. package/cordis.patch.yml +40 -0
  6. package/dist/admission/fixed-cost.d.ts +23 -0
  7. package/dist/admission/fixed-cost.js +61 -0
  8. package/dist/admission/fixed-cost.js.map +1 -0
  9. package/dist/admission/ledger.d.ts +113 -0
  10. package/dist/admission/ledger.js +176 -0
  11. package/dist/admission/ledger.js.map +1 -0
  12. package/dist/admission/retrieval.d.ts +65 -0
  13. package/dist/admission/retrieval.js +162 -0
  14. package/dist/admission/retrieval.js.map +1 -0
  15. package/dist/admission/usage.d.ts +75 -0
  16. package/dist/admission/usage.js +124 -0
  17. package/dist/admission/usage.js.map +1 -0
  18. package/dist/config.d.ts +43 -0
  19. package/dist/config.js +103 -0
  20. package/dist/config.js.map +1 -0
  21. package/dist/gate/binding.d.ts +113 -0
  22. package/dist/gate/binding.js +297 -0
  23. package/dist/gate/binding.js.map +1 -0
  24. package/dist/gate/decide.d.ts +82 -0
  25. package/dist/gate/decide.js +163 -0
  26. package/dist/gate/decide.js.map +1 -0
  27. package/dist/gate/guard.d.ts +69 -0
  28. package/dist/gate/guard.js +195 -0
  29. package/dist/gate/guard.js.map +1 -0
  30. package/dist/gate/invalidate.d.ts +112 -0
  31. package/dist/gate/invalidate.js +111 -0
  32. package/dist/gate/invalidate.js.map +1 -0
  33. package/dist/gate/plan.d.ts +86 -0
  34. package/dist/gate/plan.js +222 -0
  35. package/dist/gate/plan.js.map +1 -0
  36. package/dist/hooks/clock.d.ts +68 -0
  37. package/dist/hooks/clock.js +82 -0
  38. package/dist/hooks/clock.js.map +1 -0
  39. package/dist/hooks/execute.d.ts +79 -0
  40. package/dist/hooks/execute.js +128 -0
  41. package/dist/hooks/execute.js.map +1 -0
  42. package/dist/hooks/llm-stream.d.ts +276 -0
  43. package/dist/hooks/llm-stream.js +1008 -0
  44. package/dist/hooks/llm-stream.js.map +1 -0
  45. package/dist/hooks/pending.d.ts +89 -0
  46. package/dist/hooks/pending.js +115 -0
  47. package/dist/hooks/pending.js.map +1 -0
  48. package/dist/hooks/post-execute.d.ts +247 -0
  49. package/dist/hooks/post-execute.js +1776 -0
  50. package/dist/hooks/post-execute.js.map +1 -0
  51. package/dist/hooks/session-state.d.ts +158 -0
  52. package/dist/hooks/session-state.js +168 -0
  53. package/dist/hooks/session-state.js.map +1 -0
  54. package/dist/hooks/synthesize.d.ts +74 -0
  55. package/dist/hooks/synthesize.js +100 -0
  56. package/dist/hooks/synthesize.js.map +1 -0
  57. package/dist/host/loader.d.ts +23 -0
  58. package/dist/host/loader.js +31 -0
  59. package/dist/host/loader.js.map +1 -0
  60. package/dist/host/platform.d.ts +18 -0
  61. package/dist/host/platform.js +19 -0
  62. package/dist/host/platform.js.map +1 -0
  63. package/dist/host/root.d.ts +18 -0
  64. package/dist/host/root.js +43 -0
  65. package/dist/host/root.js.map +1 -0
  66. package/dist/index.d.ts +13 -0
  67. package/dist/index.js +866 -0
  68. package/dist/index.js.map +1 -0
  69. package/dist/projection/apply.d.ts +174 -0
  70. package/dist/projection/apply.js +137 -0
  71. package/dist/projection/apply.js.map +1 -0
  72. package/dist/projection/canonicalise.d.ts +43 -0
  73. package/dist/projection/canonicalise.js +43 -0
  74. package/dist/projection/canonicalise.js.map +1 -0
  75. package/dist/projection/counters.d.ts +65 -0
  76. package/dist/projection/counters.js +88 -0
  77. package/dist/projection/counters.js.map +1 -0
  78. package/dist/projection/truncate.d.ts +47 -0
  79. package/dist/projection/truncate.js +57 -0
  80. package/dist/projection/truncate.js.map +1 -0
  81. package/dist/prompt/protocol.d.ts +45 -0
  82. package/dist/prompt/protocol.js +56 -0
  83. package/dist/prompt/protocol.js.map +1 -0
  84. package/dist/receipts/store.d.ts +198 -0
  85. package/dist/receipts/store.js +734 -0
  86. package/dist/receipts/store.js.map +1 -0
  87. package/dist/scope/doc.d.ts +117 -0
  88. package/dist/scope/doc.js +158 -0
  89. package/dist/scope/doc.js.map +1 -0
  90. package/dist/scope/resolve.d.ts +91 -0
  91. package/dist/scope/resolve.js +146 -0
  92. package/dist/scope/resolve.js.map +1 -0
  93. package/dist/scope/store.d.ts +135 -0
  94. package/dist/scope/store.js +573 -0
  95. package/dist/scope/store.js.map +1 -0
  96. package/dist/selector/jev.d.ts +93 -0
  97. package/dist/selector/jev.js +171 -0
  98. package/dist/selector/jev.js.map +1 -0
  99. package/dist/tools/boost.d.ts +367 -0
  100. package/dist/tools/boost.js +768 -0
  101. package/dist/tools/boost.js.map +1 -0
  102. package/dist/tools/family.d.ts +26 -0
  103. package/dist/tools/family.js +26 -0
  104. package/dist/tools/family.js.map +1 -0
  105. package/dist/types.d.ts +113 -0
  106. package/dist/types.js +21 -0
  107. package/dist/types.js.map +1 -0
  108. package/locale/en.json +6 -0
  109. package/locale/zh.json +6 -0
  110. package/package.json +75 -4
@@ -0,0 +1,276 @@
1
+ /**
2
+ * The `llm/stream` hook body: the point where the plugin answers a model
3
+ * request itself instead of calling the provider.
4
+ *
5
+ * ## The synchronous contract
6
+ *
7
+ * The host treats `llm/stream` as a **synchronous waterfall**: `next()` returns
8
+ * an `AsyncIterable<StreamChunk>` and the host does `for await` over whatever
9
+ * the listener returns. An `async` listener would hand the host a
10
+ * `Promise<AsyncIterable>`, every request would fail with a `TypeError`, and the
11
+ * plugin would break the product rather than degrade it (appendix §7). The
12
+ * exported function therefore returns a **generator object synchronously**;
13
+ * every `await` lives inside the generator.
14
+ *
15
+ * ## Rule order (fixed, checks before any side effect)
16
+ *
17
+ * 1. `purpose` set -> raw `next()`. The appendix sets `purpose` **only** for
18
+ * auxiliary calls, and the host issues several on the same session id: the
19
+ * plugin's selector (`boost-selector`), `dsh-compaction-basic`
20
+ * (`compaction`) and the session-title model (`session-title`). None is a
21
+ * conversation step, so all pass through untouched: never substituted,
22
+ * never observed into `usage.request()`, never settling a mark. Observing
23
+ * one would pair a substitution with the summarizer's usage and corrupt
24
+ * `saved_input_tokens` (obligation 7); synthesizing into one would break
25
+ * compaction and write a substitute receipt for a call that never ran.
26
+ * 2. `receipts.stopped()` -> pass through, fail-closed. A store that cannot
27
+ * record evidence cannot justify a substitution.
28
+ * 3. Visibility. `resolveSession(sessionId)` returning `undefined` means the
29
+ * session is not substitutable: pass through and clear that session's queue
30
+ * (the decision cannot be honoured any more).
31
+ * 4. No pending entry -> pass through. This is the ordinary turn.
32
+ * 5. Turn validity. The queue is cleared on the **new turn's first
33
+ * `post-execute`**, which happens after the new turn's first `llm/stream`.
34
+ * An entry whose `turn` differs from the session clock's turn belongs to a
35
+ * previous turn: synthesizing it would answer the new turn with an old
36
+ * decision, and its `callId` would even match at dispatch and be accepted.
37
+ * Compare, clear and pass through (obligation 4).
38
+ * 6. Anchors intact. `ReceiptAnchors` has no turn field, so `entry.turn` being
39
+ * current is what makes the anchors current; only then is detection run
40
+ * against `options.messages` (obligation 6). A pruned carrier yields
41
+ * `pruned-reset`, a receipt that is no longer present yields
42
+ * `compaction-reset`; either clears queue + anchors and passes through. A
43
+ * body that only shares the anchor's head and tail is **not** a carrier: it
44
+ * must also carry the pruner marker or our projection's head line, or a
45
+ * middle edit would pass for the original text.
46
+ * 7. Step still payable. `post-execute` already took the entry's step, but the
47
+ * same decision can be replayed (a retried request, a re-enqueue at one
48
+ * step). The per-turn synthesis tally and the budget's paid-step count are
49
+ * re-checked immediately before synthesizing; an entry whose step can no
50
+ * longer be honoured is dropped through the abandon path (settling its mark
51
+ * as discarded) instead of emitting a duplicate `callId`.
52
+ * 8. Synthesize: `markSubstituted` -> `{kind:'substitute'}` receipt ->
53
+ * `peek` (never `take`, obligation 3) -> `yield* synthesizeTurn(entry)`.
54
+ * The upstream iterator is resolved synchronously at the waterfall point on
55
+ * every path, but the synthesis branch does not consume it. The entry must
56
+ * survive to `tools/execute`, which is the consumer that enforces the
57
+ * tamper check.
58
+ *
59
+ * The hook never calls `budget.take()`: Task 23b already took the step at
60
+ * `tools/post-execute`, and a second take would charge 2 of 8 per substitution
61
+ * (obligation 2). It only reads `count()` to verify that a paid step backs the
62
+ * synthesis.
63
+ *
64
+ * ## Per-session state (obligation 1)
65
+ *
66
+ * `HookDeps` also carries single `clock`/`budget`/`usage` instances, and a
67
+ * shared instance is cross-session contamination: another session's
68
+ * `agent/request` sets this session's `callId` turn/step, a shared
69
+ * `StepBudget(1)` starves one session, and a shared usage ledger pairs one
70
+ * session's substitution with another session's request. `SessionRuntime`
71
+ * (exported here) keys all three by `sessionId`; `HookDeps.sessions` accepts it,
72
+ * and when present it is authoritative for both this hook and Task 23b's
73
+ * helpers. The shipped wiring lives in `wireSessionEvents` (`src/index.ts`)
74
+ * and is deliberately **two** listeners, not one:
75
+ *
76
+ * ```ts
77
+ * const sessions = new SessionRuntime(cfg.stepsPerTurn)
78
+ * registerHooks(ctx, { ...deps, sessions })
79
+ *
80
+ * // agent/pre-step: the non-deprecated clock seam. It fires once per proposed
81
+ * // step, before prompt assembly, and copies the host turn/step.
82
+ * ctx.on('agent/pre-step', (payload, next) => {
83
+ * sessions.onModelRequest(sessionId, payload.turn, payload.step)
84
+ * horizon.observe(sessionId, payload.turn, payload.step)
85
+ * return next()
86
+ * })
87
+ *
88
+ * // agent/request: deprecated, kept for what the request waterfall alone
89
+ * // yields: the resolved provider/model the selector inherits (after next()),
90
+ * // the async visibility warm, and a clock fallback.
91
+ * ctx.on('agent/request', async (payload, next) => {
92
+ * sessions.onModelRequest(sessionId, payload.turn, payload.step)
93
+ * await warmVisibility(scope, registry, payload.agent, sessionId, workspaces)
94
+ * const config = await next()
95
+ * rememberRoute(routes, sessionId, config)
96
+ * return config
97
+ * })
98
+ *
99
+ * ctx.on('session/disposed', (session) => clearSession(deps, sessionId))
100
+ * ```
101
+ *
102
+ * The split is intentional: `agent/pre-step` is the seam the host documents for
103
+ * turn/step, while the selector's effective route is only available from the
104
+ * request waterfall's resolved config. Both listeners copy the clock so a host
105
+ * that drops the deprecated event still advances turns. Both record the route:
106
+ * `agent/pre-step` from the captured `modelSelection` (the primary source since
107
+ * row 37), and `agent/request` from the resolved config as the fallback for
108
+ * hosts that only populate it there; only `agent/request` warms the scope
109
+ * judgement.
110
+ *
111
+ * `onModelRequest` copies the host turn/step (never a plugin count) and resets
112
+ * that session's budget only when its turn changes. `notePlanTurn` is the
113
+ * matching rollover for the plan store: the first real request of a new turn
114
+ * drops the previous turn's plan before a new one can be parsed, so a stale
115
+ * plan cannot drive a substitution in the new turn. `clearSession(deps, id)`
116
+ * is the session-end cleanup: queue, anchors, plans, receipt state, the usage
117
+ * mark and the runtime entry, all dropped together (obligation 10). No map is
118
+ * ever handed out.
119
+ *
120
+ * ## Settlement (obligation 11)
121
+ *
122
+ * The first real request after a synthesized turn carries a `usage` chunk. The
123
+ * pass-through branch maps it to `UsageLedger.request()` and, if a mark is
124
+ * pending, calls `settle()` and appends `{kind:'substitute-settled'}` with the
125
+ * measured counts (`'unknown'` stays `'unknown'`; it is never interpolated).
126
+ * When a marked entry is abandoned (turn rollover, reset, stopped receipts,
127
+ * lost visibility, an unpayable or already-synthesized step, a vanished queue
128
+ * entry) the mark is settled and discarded **without** a settlement receipt: no
129
+ * substitution ran, so no saving exists to report (obligation 5).
130
+ *
131
+ * ## Anchor detection and our own projection
132
+ *
133
+ * The host pruner rewrites an oversized receipt in place to
134
+ * `head + PRUNE_MARKER + tail`, and apply-mode projection composes
135
+ * `head line + head + spill footer + tail`. Both preserve the receipt's head
136
+ * and tail, so "the anchor text is not present verbatim" alone would classify
137
+ * our own projection as compaction and disable substitution whenever projection
138
+ * is on. `carriesAnchor` therefore accepts the exact text, or a body holding
139
+ * the anchor's head *and* tail probes **plus** one of the two rewrites' own
140
+ * evidence: the prune marker (which then decides `pruned-reset`) or the
141
+ * projection head line, whose `output N chars; showing first H and last T`
142
+ * counts must name this anchor's length and windows. A full receipt with the
143
+ * same probes but a different middle — a file edited and re-read — carries
144
+ * neither, so it is a lost anchor (`compaction-reset`) rather than a
145
+ * substitution against content the model no longer holds.
146
+ *
147
+ * Probes are measured in code points (a UTF-16 slice can split a surrogate
148
+ * pair) and clamped to the smallest configured projection window, because
149
+ * `resolveConfig` accepts `headChars`/`tailChars` below the probe length and a
150
+ * window shorter than the probe would make our own projection look like
151
+ * compaction.
152
+ *
153
+ * Everything here is contained: a foreign store, queue, ledger, clock or
154
+ * resolver can degrade the decision, never throw out of the model request.
155
+ * `resolveStreamPlan` is synchronous and writes no receipt; its only state is
156
+ * the per-turn synthesis tally, and every receipt/queue effect (writes, clears,
157
+ * settlement) happens inside a generator after the decision.
158
+ *
159
+ * @module dsh-boost/hooks/llm-stream
160
+ */
161
+ import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm';
162
+ import { StepBudget } from '../admission/ledger.js';
163
+ import { UsageLedger } from '../admission/usage.js';
164
+ import { TurnClock } from './clock.js';
165
+ import type { HookDeps } from './post-execute.js';
166
+ /**
167
+ * Per-session clock, budget and usage ledger.
168
+ *
169
+ * The host numbers turns and steps per session; a single instance therefore
170
+ * lets one session's `agent/request` stamp another session's derived `callId`,
171
+ * lets one session's `StepBudget(1)` starve the next, and pairs one session's
172
+ * substitution with another session's request. The runtime keys all three by
173
+ * `sessionId` and is the only place a per-session primitive is created.
174
+ *
175
+ * The map is private: callers get the objects, never the map, and
176
+ * {@link SessionRuntime.clear} is the only way an entry leaves. `onModelRequest`
177
+ * is driven by Task 23c-2 from the host's `agent/request` payload; this module
178
+ * cannot see that event itself. A new turn resets that session's budget (the
179
+ * budget is per-turn, not per-lifetime); a non-finite or backwards turn is
180
+ * ignored by `TurnClock` and therefore resets nothing.
181
+ */
182
+ export declare class SessionRuntime {
183
+ private readonly bySession;
184
+ private readonly stepsPerTurn;
185
+ constructor(stepsPerTurn?: number);
186
+ /** The session's clock, created on first use. */
187
+ clockFor(sessionId: string): TurnClock;
188
+ /** The session's turn budget, created on first use. */
189
+ budgetFor(sessionId: string): StepBudget;
190
+ /** The session's usage ledger, created on first use. */
191
+ usageFor(sessionId: string): UsageLedger;
192
+ /**
193
+ * Record one host request for a session.
194
+ *
195
+ * `turn`/`step` are the host's numbers, copied through `TurnClock` (which
196
+ * ignores non-finite and backwards turns). A turn change is the only thing
197
+ * that resets the budget: a second request in one turn must keep the spend.
198
+ */
199
+ onModelRequest(sessionId: string, turn: number, step?: number): void;
200
+ /**
201
+ * Reconcile this session's plan store with `turn`; `true` on a turn change.
202
+ *
203
+ * The plan lives in `HookDeps.plans` and is keyed by session only, so
204
+ * without this note a turn that emits no new plan keeps the previous turn's
205
+ * one, and its remaining steps can still drive a substitution. The stream
206
+ * hook calls this once per **real** request (never for an auxiliary
207
+ * `purpose`, which is not a conversation step) and clears the plan map when
208
+ * it returns true, before that request's response could write a new plan.
209
+ * The first call reports true so a seeded map cannot outlive its first
210
+ * request; `clearSession` drops the note with the rest of the entry.
211
+ */
212
+ notePlanTurn(sessionId: string, turn: number): boolean;
213
+ /** Drop everything this runtime holds for one session. */
214
+ clear(sessionId: string): void;
215
+ /** Number of sessions with state (not the number ever seen). */
216
+ size(): number;
217
+ private entry;
218
+ }
219
+ /**
220
+ * The session's clock: the per-session runtime when wired, the shared instance
221
+ * otherwise — but only for the one session that instance belongs to.
222
+ *
223
+ * Exported because `tools/post-execute` must resolve the *same* clock for the
224
+ * turn/step it stamps into a `callId`; two copies of this precedence rule could
225
+ * drift and let the decision and the stream hook disagree about one session.
226
+ */
227
+ export declare function sessionClock(deps: HookDeps, sessionId: string): TurnClock | undefined;
228
+ /** The session's turn budget; the same precedence as {@link sessionClock}. */
229
+ export declare function sessionBudget(deps: HookDeps, sessionId: string): StepBudget | undefined;
230
+ /** The session's usage ledger; the same precedence as {@link sessionClock}. */
231
+ export declare function sessionUsage(deps: HookDeps, sessionId: string): UsageLedger | undefined;
232
+ /**
233
+ * Whether the receipt store has stopped writing, fail-closed.
234
+ *
235
+ * A missing `stopped` (a partial store in a test or an older host) is "not
236
+ * stopped", so the ordinary path is unchanged. A store that *throws* cannot
237
+ * record evidence, which is exactly what stopped means.
238
+ */
239
+ export declare function receiptsStopped(deps: HookDeps): boolean;
240
+ /**
241
+ * Consume the session's usage mark without reporting a saving.
242
+ *
243
+ * `markSubstituted` has no unmark: a mark left behind by an abandoned entry
244
+ * would make the next real request settle a substitution that never ran
245
+ * (obligation 5). `settle()` here is the discard, not a measurement. The parked
246
+ * plan evidence goes with the mark: nothing will ever write its receipt.
247
+ */
248
+ export declare function settleDiscarded(deps: HookDeps, sessionId: string): void;
249
+ /**
250
+ * Build the `llm/stream` listener.
251
+ *
252
+ * Returns a **synchronous** function returning an `AsyncIterable`; see the
253
+ * module header for why an `async` function here breaks every request. Any
254
+ * `purpose`-tagged call (selector, compaction, session-title) returns `next()`
255
+ * untouched: never observed, never substituted. Every real request is decided
256
+ * synchronously by {@link resolveStreamPlan} and then answered by a generator.
257
+ *
258
+ * The upstream iterator is resolved **at the waterfall point on every path**,
259
+ * before any generator body runs. The host's terminal is a lazy async iterable
260
+ * (starting it is what calls the model), so resolving it on the synthesis path
261
+ * costs nothing; it is only consumed if the pending entry vanished and the real
262
+ * model has to answer. Resolving it lazily inside the generator would resume a
263
+ * waterfall the host may already have moved past.
264
+ */
265
+ export declare function streamHook(deps: HookDeps): (options: GenerateOptions, next: () => AsyncIterable<StreamChunk>) => AsyncIterable<StreamChunk>;
266
+ /**
267
+ * Drop every per-session trace the plugin keeps for `sessionId`.
268
+ *
269
+ * This is the session-end cleanup `src/index.ts` calls from its
270
+ * `session/disposed` listener: the receipt/dispatch store ships its own
271
+ * `clear`, but it does not own the queue, the anchors, the plan map or the
272
+ * per-session runtime, so the caller would otherwise have to know four separate
273
+ * clears. A pending usage mark is settled first so a mark cannot outlive the
274
+ * session it belongs to.
275
+ */
276
+ export declare function clearSession(deps: HookDeps, sessionId: string): void;