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,1008 @@
1
+ import { StepBudget } from '../admission/ledger.js';
2
+ import { UsageLedger } from '../admission/usage.js';
3
+ import { DEFAULT_CONFIG } from '../config.js';
4
+ import { looksPruned } from '../gate/invalidate.js';
5
+ import { parsePlan } from '../gate/plan.js';
6
+ import { TurnClock } from './clock.js';
7
+ import { synthesizeTurn } from './synthesize.js';
8
+ import { appendReceipt, callPreview, clearAnchors, clearPlan, clearPending, clockTurnOf, peekPending, } from './session-state.js';
9
+ /** Default head/tail probe length for a receipt rewritten in place. */
10
+ const ANCHOR_PROBE_CHARS = 32;
11
+ /**
12
+ * Per-session clock, budget and usage ledger.
13
+ *
14
+ * The host numbers turns and steps per session; a single instance therefore
15
+ * lets one session's `agent/request` stamp another session's derived `callId`,
16
+ * lets one session's `StepBudget(1)` starve the next, and pairs one session's
17
+ * substitution with another session's request. The runtime keys all three by
18
+ * `sessionId` and is the only place a per-session primitive is created.
19
+ *
20
+ * The map is private: callers get the objects, never the map, and
21
+ * {@link SessionRuntime.clear} is the only way an entry leaves. `onModelRequest`
22
+ * is driven by Task 23c-2 from the host's `agent/request` payload; this module
23
+ * cannot see that event itself. A new turn resets that session's budget (the
24
+ * budget is per-turn, not per-lifetime); a non-finite or backwards turn is
25
+ * ignored by `TurnClock` and therefore resets nothing.
26
+ */
27
+ export class SessionRuntime {
28
+ bySession = new Map();
29
+ stepsPerTurn;
30
+ constructor(stepsPerTurn = DEFAULT_CONFIG.stepsPerTurn) {
31
+ // `StepBudget` already treats a non-positive max as empty; only a
32
+ // non-finite value (which no resolved config can produce) falls back.
33
+ this.stepsPerTurn = Number.isFinite(stepsPerTurn)
34
+ ? stepsPerTurn
35
+ : DEFAULT_CONFIG.stepsPerTurn;
36
+ }
37
+ /** The session's clock, created on first use. */
38
+ clockFor(sessionId) {
39
+ return this.entry(sessionId).clock;
40
+ }
41
+ /** The session's turn budget, created on first use. */
42
+ budgetFor(sessionId) {
43
+ return this.entry(sessionId).budget;
44
+ }
45
+ /** The session's usage ledger, created on first use. */
46
+ usageFor(sessionId) {
47
+ return this.entry(sessionId).usage;
48
+ }
49
+ /**
50
+ * Record one host request for a session.
51
+ *
52
+ * `turn`/`step` are the host's numbers, copied through `TurnClock` (which
53
+ * ignores non-finite and backwards turns). A turn change is the only thing
54
+ * that resets the budget: a second request in one turn must keep the spend.
55
+ */
56
+ onModelRequest(sessionId, turn, step) {
57
+ const entry = this.entry(sessionId);
58
+ const before = entry.clock.turn();
59
+ entry.clock.onModelRequest(turn, step);
60
+ if (entry.clock.turn() !== before)
61
+ entry.budget.reset();
62
+ }
63
+ /**
64
+ * Reconcile this session's plan store with `turn`; `true` on a turn change.
65
+ *
66
+ * The plan lives in `HookDeps.plans` and is keyed by session only, so
67
+ * without this note a turn that emits no new plan keeps the previous turn's
68
+ * one, and its remaining steps can still drive a substitution. The stream
69
+ * hook calls this once per **real** request (never for an auxiliary
70
+ * `purpose`, which is not a conversation step) and clears the plan map when
71
+ * it returns true, before that request's response could write a new plan.
72
+ * The first call reports true so a seeded map cannot outlive its first
73
+ * request; `clearSession` drops the note with the rest of the entry.
74
+ */
75
+ notePlanTurn(sessionId, turn) {
76
+ const entry = this.entry(sessionId);
77
+ if (entry.planTurn === turn)
78
+ return false;
79
+ entry.planTurn = turn;
80
+ return true;
81
+ }
82
+ /** Drop everything this runtime holds for one session. */
83
+ clear(sessionId) {
84
+ this.bySession.delete(sessionId);
85
+ }
86
+ /** Number of sessions with state (not the number ever seen). */
87
+ size() {
88
+ return this.bySession.size;
89
+ }
90
+ entry(sessionId) {
91
+ const existing = this.bySession.get(sessionId);
92
+ if (existing !== undefined)
93
+ return existing;
94
+ const entry = {
95
+ clock: new TurnClock(),
96
+ budget: new StepBudget(this.stepsPerTurn),
97
+ usage: new UsageLedger(),
98
+ };
99
+ this.bySession.set(sessionId, entry);
100
+ return entry;
101
+ }
102
+ }
103
+ // ---------------------------------------------------------------------------
104
+ // Defensive readers: every foreign call is wrapped
105
+ // ---------------------------------------------------------------------------
106
+ /** The request's session id, or `undefined` when the host supplied none. */
107
+ function sessionIdOf(options) {
108
+ const id = options?.sessionId;
109
+ return typeof id === 'string' && id.length > 0 ? id : undefined;
110
+ }
111
+ /**
112
+ * Which session has been lent the shared fallback runtime.
113
+ *
114
+ * `apply` always passes `sessions`, so this exists for embedders and tests that
115
+ * hand in one `clock`/`budget`/`usage` instead. Those three carry per-session
116
+ * state — a turn's step counter, a pending usage mark — so lending one to a
117
+ * second session attributes B's tokens to A's candidate. That surfaces as a
118
+ * saving that never happened, which is the one error this plugin must not
119
+ * produce. The first session to arrive keeps the loan; every other session gets
120
+ * `undefined`, which each caller already reads as "no substitution" (fail
121
+ * closed), and the warning is emitted once per deps object rather than per call.
122
+ */
123
+ const fallbackOwner = new WeakMap();
124
+ /** Whether the shared fallback runtime may serve this session. */
125
+ function mayBorrowShared(deps, sessionId) {
126
+ const held = fallbackOwner.get(deps);
127
+ if (held === undefined) {
128
+ fallbackOwner.set(deps, { sessionId, warned: false });
129
+ return true;
130
+ }
131
+ if (held.sessionId === sessionId)
132
+ return true;
133
+ if (!held.warned) {
134
+ held.warned = true;
135
+ try {
136
+ deps.logger?.warn(`dsh-boost: no per-session runtime is wired, and session ${sessionId} is not the one already using the shared clock/budget/usage; substitution stays off for it rather than mixing two sessions' measurements`);
137
+ }
138
+ catch {
139
+ // A logger that throws must not turn a measurement guard into a failure.
140
+ }
141
+ }
142
+ return false;
143
+ }
144
+ /**
145
+ * The session's clock: the per-session runtime when wired, the shared instance
146
+ * otherwise — but only for the one session that instance belongs to.
147
+ *
148
+ * Exported because `tools/post-execute` must resolve the *same* clock for the
149
+ * turn/step it stamps into a `callId`; two copies of this precedence rule could
150
+ * drift and let the decision and the stream hook disagree about one session.
151
+ */
152
+ export function sessionClock(deps, sessionId) {
153
+ try {
154
+ const owned = deps.sessions?.clockFor(sessionId);
155
+ if (owned !== undefined)
156
+ return owned;
157
+ }
158
+ catch {
159
+ // Fall through to the shared instance, subject to the ownership rule.
160
+ }
161
+ return deps.clock !== undefined && mayBorrowShared(deps, sessionId) ? deps.clock : undefined;
162
+ }
163
+ /** The session's turn budget; the same precedence as {@link sessionClock}. */
164
+ export function sessionBudget(deps, sessionId) {
165
+ try {
166
+ const owned = deps.sessions?.budgetFor(sessionId);
167
+ if (owned !== undefined)
168
+ return owned;
169
+ }
170
+ catch {
171
+ // Fall through to the shared instance, subject to the ownership rule.
172
+ }
173
+ return deps.budget !== undefined && mayBorrowShared(deps, sessionId) ? deps.budget : undefined;
174
+ }
175
+ /** The session's usage ledger; the same precedence as {@link sessionClock}. */
176
+ export function sessionUsage(deps, sessionId) {
177
+ try {
178
+ const owned = deps.sessions?.usageFor(sessionId);
179
+ if (owned !== undefined)
180
+ return owned;
181
+ }
182
+ catch {
183
+ // Fall through to the shared instance, subject to the ownership rule.
184
+ }
185
+ return deps.usage !== undefined && mayBorrowShared(deps, sessionId) ? deps.usage : undefined;
186
+ }
187
+ /** The session's anchors without ever failing the request. */
188
+ function anchorsOf(deps, sessionId) {
189
+ try {
190
+ return deps.anchors?.get(sessionId);
191
+ }
192
+ catch {
193
+ return undefined;
194
+ }
195
+ }
196
+ /**
197
+ * Whether the receipt store has stopped writing, fail-closed.
198
+ *
199
+ * A missing `stopped` (a partial store in a test or an older host) is "not
200
+ * stopped", so the ordinary path is unchanged. A store that *throws* cannot
201
+ * record evidence, which is exactly what stopped means.
202
+ */
203
+ export function receiptsStopped(deps) {
204
+ try {
205
+ const store = deps.receipts;
206
+ if (store == null || typeof store.stopped !== 'function')
207
+ return false;
208
+ return store.stopped() === true;
209
+ }
210
+ catch {
211
+ return true;
212
+ }
213
+ }
214
+ /**
215
+ * Whether the session resolves to a workspace.
216
+ *
217
+ * The stream hook's rule only needs the resolver: a session that does not
218
+ * resolve has no substitute-able workspace, so the decision cannot be honoured.
219
+ * The live scope-document check lives in `tools/post-execute`, which owns the
220
+ * async document read; `resolveSession` is synchronous by contract.
221
+ */
222
+ function visibleSession(deps, sessionId) {
223
+ try {
224
+ const resolve = deps.resolveSession;
225
+ if (typeof resolve !== 'function')
226
+ return false;
227
+ return typeof resolve(sessionId) === 'string';
228
+ }
229
+ catch {
230
+ return false;
231
+ }
232
+ }
233
+ /** The host turn and the entry's turn are the same, number or stringified number. */
234
+ function sameTurn(entryTurn, clockTurn) {
235
+ return String(entryTurn) === String(clockTurn);
236
+ }
237
+ /** A receipt's `turn` field is a number; entry turns may already be strings. */
238
+ function turnNumberOf(turn) {
239
+ if (typeof turn === 'number' && Number.isFinite(turn))
240
+ return turn;
241
+ const parsed = Number(turn);
242
+ return Number.isFinite(parsed) ? parsed : 0;
243
+ }
244
+ // ---------------------------------------------------------------------------
245
+ // Anchor detection against the outgoing messages (obligation 6)
246
+ // ---------------------------------------------------------------------------
247
+ /**
248
+ * Every text-block body the model will see in this request.
249
+ *
250
+ * `RequestMessage.content` is an array of blocks; only `text` blocks carry
251
+ * receipt bodies. Blocks are kept separate so a mixed message cannot make two
252
+ * unrelated texts look like one receipt. A malformed message is skipped, never
253
+ * a throw: `options.messages` is host-shaped data.
254
+ */
255
+ function messageTexts(messages) {
256
+ if (!Array.isArray(messages))
257
+ return [];
258
+ const bodies = [];
259
+ for (const message of messages) {
260
+ const content = message?.content;
261
+ if (!Array.isArray(content))
262
+ continue;
263
+ for (const block of content) {
264
+ if (typeof block !== 'object' || block === null)
265
+ continue;
266
+ const { type, text } = block;
267
+ if (type === 'text' && typeof text === 'string')
268
+ bodies.push(text);
269
+ }
270
+ }
271
+ return bodies;
272
+ }
273
+ /**
274
+ * The head/tail probe windows, clamped to the projection's own windows.
275
+ *
276
+ * Our projection keeps `headChars`/`tailChars` code points of the receipt, so
277
+ * a probe longer than a configured window can never match a projected body and
278
+ * would report `compaction-reset`. `resolveConfig` accepts any finite value
279
+ * (including 0), so the window is the smallest one any family configures,
280
+ * capped at {@link ANCHOR_PROBE_CHARS}; a 0 window drops that side of the
281
+ * probe and leaves only the other. With the design defaults this is 32/32.
282
+ */
283
+ function anchorProbe(deps) {
284
+ let head = ANCHOR_PROBE_CHARS;
285
+ let tail = ANCHOR_PROBE_CHARS;
286
+ try {
287
+ const projection = deps.config?.projection;
288
+ if (typeof projection !== 'object' || projection === null)
289
+ return { head, tail };
290
+ for (const raw of Object.values(projection)) {
291
+ const params = raw;
292
+ if (typeof params?.headChars === 'number' && Number.isFinite(params.headChars)) {
293
+ head = Math.min(head, Math.max(0, params.headChars));
294
+ }
295
+ if (typeof params?.tailChars === 'number' && Number.isFinite(params.tailChars)) {
296
+ tail = Math.min(tail, Math.max(0, params.tailChars));
297
+ }
298
+ }
299
+ }
300
+ catch {
301
+ return { head: ANCHOR_PROBE_CHARS, tail: ANCHOR_PROBE_CHARS };
302
+ }
303
+ return { head, tail };
304
+ }
305
+ /**
306
+ * The head line our own projection writes: `[output N chars; showing first H
307
+ * and last T]`. The counts use `toLocaleString('en-US')`, hence the commas.
308
+ */
309
+ const PROJECTION_HEADER = /^\[output ([\d,]+) chars; showing first ([\d,]+) and last ([\d,]+)\]$/;
310
+ /** One `en-US`-formatted count from a projection head line. */
311
+ function headerCount(raw) {
312
+ if (raw === undefined)
313
+ return undefined;
314
+ const value = Number(raw.replaceAll(',', ''));
315
+ return Number.isSafeInteger(value) ? value : undefined;
316
+ }
317
+ /**
318
+ * Whether `body` is our own projection of `anchor`.
319
+ *
320
+ * A projected receipt is `head line + head + spill footer + tail`. The head
321
+ * line names the anchor's total code points and both window sizes, and the two
322
+ * windows are the anchor's own first/last code points. A full receipt that
323
+ * merely shares the anchor's head and tail cannot produce that line, so this
324
+ * closes the probe collision without reading the middle (which the projection
325
+ * removed) and without a new stored field. Old anchors that cannot be verified
326
+ * this way simply do not match, which fails closed.
327
+ */
328
+ function ownProjectionCarries(body, anchor) {
329
+ const newline = body.indexOf('\n');
330
+ if (newline === -1)
331
+ return false;
332
+ const match = PROJECTION_HEADER.exec(body.slice(0, newline));
333
+ if (match === null)
334
+ return false;
335
+ const output = headerCount(match[1]);
336
+ const headLen = headerCount(match[2]);
337
+ const tailLen = headerCount(match[3]);
338
+ if (output === undefined || headLen === undefined || tailLen === undefined)
339
+ return false;
340
+ if (headLen <= 0 && tailLen <= 0)
341
+ return false;
342
+ const points = Array.from(anchor);
343
+ if (output !== points.length)
344
+ return false;
345
+ if (headLen + tailLen >= points.length)
346
+ return false;
347
+ const head = headLen > 0 ? points.slice(0, headLen).join('') : '';
348
+ const tail = tailLen > 0 ? points.slice(-tailLen).join('') : '';
349
+ return body.startsWith(`${match[0]}\n${head}`) && (tailLen === 0 || body.endsWith(tail));
350
+ }
351
+ /**
352
+ * Whether `body` still carries `anchor`, verbatim or as a verified in-place
353
+ * rewrite.
354
+ *
355
+ * The host pruner replaces the middle of an oversized receipt with
356
+ * `PRUNE_MARKER` while preserving a head and a tail; apply-mode projection
357
+ * composes head line + head + spill footer + tail. Both keep the anchor's
358
+ * beginning and end, so a body holding both probes *and* the rewrite's own
359
+ * evidence is the same receipt rewritten in place.
360
+ *
361
+ * Sharing the two probes alone is not identity: a file edited in the middle and
362
+ * re-read produces a full receipt with the same 32-character head and tail but
363
+ * a different body. Accepting it would substitute against content the model no
364
+ * longer holds, so a probe match must be accompanied by the pruner marker or
365
+ * our projection's head line. Anything else is a lost anchor (fail closed).
366
+ *
367
+ * Probes are sliced by **code point**, exactly like `truncate`: a UTF-16 slice
368
+ * can end on half a surrogate pair, and a lone surrogate is not a substring a
369
+ * correctly projected body has to contain. Short anchors whose two windows
370
+ * would cover the whole text get no probe treatment: at that size the exact
371
+ * text either is present or the receipt is gone.
372
+ */
373
+ function carriesAnchor(body, anchor, probe) {
374
+ if (body.includes(anchor))
375
+ return true;
376
+ const points = Array.from(anchor);
377
+ const headLen = Math.min(probe.head, points.length);
378
+ const tailLen = Math.min(probe.tail, points.length);
379
+ if (headLen === 0 && tailLen === 0)
380
+ return false;
381
+ if (points.length <= headLen + tailLen)
382
+ return false;
383
+ const head = headLen > 0 ? points.slice(0, headLen).join('') : '';
384
+ const tail = tailLen > 0 ? points.slice(-tailLen).join('') : '';
385
+ const start = headLen > 0 ? body.indexOf(head) : 0;
386
+ if (headLen > 0 && start === -1)
387
+ return false;
388
+ if (tailLen > 0 && body.indexOf(tail, start + headLen) === -1)
389
+ return false;
390
+ return looksPruned(body) || ownProjectionCarries(body, anchor);
391
+ }
392
+ /**
393
+ * Why the decision's anchored receipts are no longer trustworthy, if they are.
394
+ *
395
+ * Marker precedence matches `invalidate`: any carried body that contains the
396
+ * pruner literal means `pruned-reset`, because the pruner is the common case
397
+ * and it leaves the receipt in place. Only when no anchor was pruned does a
398
+ * missing carrier mean `compaction-reset` (the history was replaced by a
399
+ * summary). No anchors at all is vacuously intact: `post-execute` always writes
400
+ * them with a commit, but a missing evidence store must not block substitution
401
+ * forever.
402
+ *
403
+ * An empty anchor cannot be located in any message and is skipped; `invalidate`
404
+ * treats an empty anchor as a real value, but the stream hook has no receipt
405
+ * body to compare it with, and refusing every substitution on one empty tool
406
+ * result would be worse than the uncertainty.
407
+ */
408
+ function anchorResetOf(anchors, messages, probe) {
409
+ if (anchors == null)
410
+ return undefined;
411
+ const record = anchors.anchors;
412
+ if (typeof record !== 'object' || record === null)
413
+ return undefined;
414
+ const values = Object.values(record);
415
+ if (values.length === 0)
416
+ return undefined;
417
+ const texts = values.filter((text) => typeof text === 'string' && text.length > 0);
418
+ if (texts.length === 0) {
419
+ // An empty anchor is a real value the check skips (it cannot be located in
420
+ // any message). Any other unverifiable shape — an object from an older or
421
+ // foreign anchor store — must fail closed instead: treating it as "no
422
+ // anchors" would substitute on evidence this code cannot read.
423
+ return values.every((value) => value === '') ? undefined : 'compaction-reset';
424
+ }
425
+ const bodies = messageTexts(messages);
426
+ let compacted = false;
427
+ for (const anchor of texts) {
428
+ if (looksPruned(anchor))
429
+ return 'pruned-reset';
430
+ const carriers = bodies.filter((body) => carriesAnchor(body, anchor, probe));
431
+ if (carriers.length === 0) {
432
+ compacted = true;
433
+ continue;
434
+ }
435
+ if (carriers.some((body) => looksPruned(body)))
436
+ return 'pruned-reset';
437
+ }
438
+ return compacted ? 'compaction-reset' : undefined;
439
+ }
440
+ /**
441
+ * Per-session synthesis history, keyed by `HookDeps` first so two plugin
442
+ * instances in one process cannot read each other's session. It holds one turn
443
+ * per session and dies with the assembly; `clearSession` drops the session.
444
+ */
445
+ const SYNTHESIS_TALLY = new WeakMap();
446
+ /** The session's synthesis tally, if this turn has one. */
447
+ function synthesisTallyOf(deps, sessionId) {
448
+ try {
449
+ return SYNTHESIS_TALLY.get(deps)?.get(sessionId);
450
+ }
451
+ catch {
452
+ return undefined;
453
+ }
454
+ }
455
+ /** Count one synthesized turn, starting a new tally when the turn changed. */
456
+ function recordSynthesis(deps, sessionId, turn, callId) {
457
+ try {
458
+ let bySession = SYNTHESIS_TALLY.get(deps);
459
+ if (bySession === undefined) {
460
+ bySession = new Map();
461
+ SYNTHESIS_TALLY.set(deps, bySession);
462
+ }
463
+ let tally = bySession.get(sessionId);
464
+ if (tally === undefined || tally.turn !== turn) {
465
+ tally = { turn, count: 0, callIds: new Set() };
466
+ bySession.set(sessionId, tally);
467
+ }
468
+ tally.count += 1;
469
+ tally.callIds.add(callId);
470
+ }
471
+ catch {
472
+ // A tally miss costs a duplicate guard, never this request.
473
+ }
474
+ }
475
+ /** Drop one session's synthesis history at session end. */
476
+ function forgetSynthesis(deps, sessionId) {
477
+ try {
478
+ SYNTHESIS_TALLY.get(deps)?.delete(sessionId);
479
+ }
480
+ catch {
481
+ // Same: the tally is a guard, not a precondition.
482
+ }
483
+ }
484
+ /**
485
+ * Whether the entry's step can no longer be honoured.
486
+ *
487
+ * Two independent facts make a still-live entry unhonourable: its deterministic
488
+ * call id was already synthesized in this turn (a retry or a re-enqueue at one
489
+ * step), or the turn's paid steps are already used up by earlier syntheses.
490
+ * A budget that reports no spend at all is a fixture/legacy shape rather than
491
+ * proof of a step; the call-id half still applies there.
492
+ */
493
+ function synthesisBlocked(deps, sessionId, entry, turn) {
494
+ const tally = synthesisTallyOf(deps, sessionId);
495
+ const current = tally !== undefined && sameTurn(tally.turn, turn) ? tally : undefined;
496
+ if (current !== undefined && current.callIds.has(entry.callId))
497
+ return true;
498
+ const budget = sessionBudget(deps, sessionId);
499
+ if (budget === undefined)
500
+ return false;
501
+ let spent;
502
+ try {
503
+ spent = budget.count();
504
+ }
505
+ catch {
506
+ return false;
507
+ }
508
+ if (!Number.isFinite(spent) || spent <= 0)
509
+ return false;
510
+ return (current?.count ?? 0) >= spent;
511
+ }
512
+ /**
513
+ * The rule order as pure, synchronous decision logic.
514
+ *
515
+ * Nothing here writes a receipt or takes a step: every check completes before
516
+ * the first effect. `post-execute` already took the budget at the decision
517
+ * point (obligation 2), so this function never touches the budget.
518
+ */
519
+ function resolveStreamPlan(deps, options) {
520
+ const sessionId = sessionIdOf(options);
521
+ // The selector guard is the first rule and lives in `streamHook`, which
522
+ // returns `next()` before this function runs: a selector request must not
523
+ // even be observed, so it cannot become a plan.
524
+ if (receiptsStopped(deps)) {
525
+ // Fail-closed: the decision cannot be recorded, so it will never be
526
+ // synthesized. Empty the queue and settle the decision-time mark even when
527
+ // the queue entry is already gone (the dispatch side may have consumed it);
528
+ // otherwise the mark would settle a later real request as a substitution.
529
+ return passPlan(deps, sessionId, { clearQueue: true, clearAnchors: false }, true);
530
+ }
531
+ if (sessionId === undefined)
532
+ return { kind: 'pass', sessionId };
533
+ if (!visibleSession(deps, sessionId)) {
534
+ return passPlan(deps, sessionId, { clearQueue: true, clearAnchors: false });
535
+ }
536
+ const entry = peekPending(deps, sessionId);
537
+ if (entry === undefined)
538
+ return { kind: 'pass', sessionId };
539
+ const turn = clockTurnOf(deps, sessionId);
540
+ if (turn === undefined || !sameTurn(entry.turn, turn)) {
541
+ return {
542
+ kind: 'pass',
543
+ sessionId,
544
+ abandon: { entry, clearQueue: true, clearAnchors: false },
545
+ };
546
+ }
547
+ // A blank call id cannot be dispatched and must not be "repaired" here: the
548
+ // execute-side tamper check would compare a different id and reject silently.
549
+ if (typeof entry.callId !== 'string' || entry.callId.trim().length === 0) {
550
+ return {
551
+ kind: 'pass',
552
+ sessionId,
553
+ abandon: { entry, clearQueue: true, clearAnchors: false },
554
+ };
555
+ }
556
+ const anchors = anchorsOf(deps, sessionId);
557
+ const reset = anchorResetOf(anchors, options?.messages, anchorProbe(deps));
558
+ if (reset !== undefined) {
559
+ return {
560
+ kind: 'pass',
561
+ sessionId,
562
+ abandon: {
563
+ entry,
564
+ clearQueue: true,
565
+ clearAnchors: true,
566
+ reset: {
567
+ code: reset,
568
+ stepId: typeof anchors?.stepId === 'string' ? anchors.stepId : 'root',
569
+ turn: turn,
570
+ },
571
+ },
572
+ };
573
+ }
574
+ // Re-check the step immediately before synthesizing. The turn/step checks
575
+ // above validate identity, not spend: a retried or re-enqueued request in the
576
+ // same turn would otherwise emit a second substitute receipt with the same
577
+ // call id, bypassing the per-turn budget the decision already consumed. The
578
+ // entry is dropped through the ordinary abandon path so its usage mark is
579
+ // settled as discarded rather than left to a later real request.
580
+ if (synthesisBlocked(deps, sessionId, entry, turn)) {
581
+ return {
582
+ kind: 'pass',
583
+ sessionId,
584
+ abandon: { entry, clearQueue: true, clearAnchors: true },
585
+ };
586
+ }
587
+ return { kind: 'synthesize', sessionId, entry };
588
+ }
589
+ /**
590
+ * A pass plan that abandons the session's pending entry, when one exists.
591
+ *
592
+ * `discardMark` makes the plan settle the usage mark even when no entry is
593
+ * left; the stopped-store branch needs that because the dispatch side may
594
+ * already have consumed the entry.
595
+ */
596
+ function passPlan(deps, sessionId, abandons, discardMark = false) {
597
+ if (sessionId === undefined)
598
+ return { kind: 'pass', sessionId };
599
+ const entry = peekPending(deps, sessionId);
600
+ if (entry === undefined)
601
+ return { kind: 'pass', sessionId, ...(discardMark ? { discardMark } : {}) };
602
+ return {
603
+ kind: 'pass',
604
+ sessionId,
605
+ abandon: { entry, ...abandons },
606
+ ...(discardMark ? { discardMark } : {}),
607
+ };
608
+ }
609
+ // ---------------------------------------------------------------------------
610
+ // Effects
611
+ // ---------------------------------------------------------------------------
612
+ /**
613
+ * Consume the session's usage mark without reporting a saving.
614
+ *
615
+ * `markSubstituted` has no unmark: a mark left behind by an abandoned entry
616
+ * would make the next real request settle a substitution that never ran
617
+ * (obligation 5). `settle()` here is the discard, not a measurement. The parked
618
+ * plan evidence goes with the mark: nothing will ever write its receipt.
619
+ */
620
+ export function settleDiscarded(deps, sessionId) {
621
+ try {
622
+ sessionUsage(deps, sessionId)?.settle();
623
+ }
624
+ catch {
625
+ // A foreign ledger can only cost a measurement.
626
+ }
627
+ forgetEvidence(deps, sessionId);
628
+ }
629
+ /**
630
+ * Plan/guards evidence parked between synthesis and settlement.
631
+ *
632
+ * The settled receipt is written at the first real request after the
633
+ * synthesized turn, when the queue entry is already gone; the synth-time
634
+ * receipt has it from the entry, this park hands it to the settle. Keyed by
635
+ * `HookDeps` first so two plugin instances in one process cannot read each
636
+ * other's session, and a `WeakMap` lets the whole map die with the assembly.
637
+ */
638
+ const PENDING_EVIDENCE = new WeakMap();
639
+ /** Park the evidence for the session's next settlement, replacing any earlier. */
640
+ function rememberEvidence(deps, sessionId, evidence) {
641
+ let bySession = PENDING_EVIDENCE.get(deps);
642
+ if (bySession === undefined) {
643
+ bySession = new Map();
644
+ PENDING_EVIDENCE.set(deps, bySession);
645
+ }
646
+ bySession.set(sessionId, evidence);
647
+ }
648
+ /** Take (and forget) the evidence one settlement consumes. */
649
+ function takeEvidence(deps, sessionId) {
650
+ const bySession = PENDING_EVIDENCE.get(deps);
651
+ const evidence = bySession?.get(sessionId);
652
+ bySession?.delete(sessionId);
653
+ return evidence;
654
+ }
655
+ /** Drop evidence that no settlement will ever consume. */
656
+ function forgetEvidence(deps, sessionId) {
657
+ PENDING_EVIDENCE.get(deps)?.delete(sessionId);
658
+ }
659
+ /** Record the synthesis mark for the session's pairing. */
660
+ function markSubstitutedFor(deps, sessionId, candidateId) {
661
+ try {
662
+ sessionUsage(deps, sessionId)?.markSubstituted(candidateId);
663
+ }
664
+ catch {
665
+ // A ledger miss costs a measurement, never this turn.
666
+ }
667
+ }
668
+ /** The synth-time receipt: the event, before any measurement exists. */
669
+ async function appendSubstituteReceipt(deps, sessionId, entry) {
670
+ const evidence = entry.evidence;
671
+ await appendReceipt(deps, {
672
+ version: 1,
673
+ ts: new Date().toISOString(),
674
+ sessionId,
675
+ turn: turnNumberOf(entry.turn),
676
+ stepId: 'root',
677
+ kind: 'substitute',
678
+ code: 'substituted',
679
+ tool: entry.name,
680
+ callId: entry.callId,
681
+ candidateId: entry.candidateId,
682
+ // G2: the plan the decision came from and the guards that qualified the
683
+ // candidate, capped by `substitutionEvidence` before they reach the line.
684
+ ...(evidence === undefined ? {} : evidence),
685
+ // The synthesized call has no tool result yet; its name and bound args are
686
+ // the evidence for why this turn asked for it.
687
+ args: entry.args,
688
+ preview: callPreview(entry.name, entry.args),
689
+ // Measured only after the next real request; `'unknown'` never counts.
690
+ saved_input_tokens: 'unknown',
691
+ cache_hit_delta: null,
692
+ output_tokens: 'unknown',
693
+ });
694
+ }
695
+ /** Settle a pending mark at the first after-mark request and report it. */
696
+ async function settlePendingMark(deps, sessionId) {
697
+ const ledger = sessionUsage(deps, sessionId);
698
+ if (ledger === undefined)
699
+ return;
700
+ let candidateId;
701
+ let settled;
702
+ try {
703
+ const pending = ledger.pendingCandidateId();
704
+ if (typeof pending !== 'string' || pending.length === 0)
705
+ return;
706
+ candidateId = pending;
707
+ settled = ledger.settle();
708
+ }
709
+ catch {
710
+ return;
711
+ }
712
+ await appendReceipt(deps, {
713
+ version: 1,
714
+ ts: new Date().toISOString(),
715
+ sessionId,
716
+ turn: clockTurnOf(deps, sessionId) ?? 0,
717
+ stepId: 'root',
718
+ kind: 'substitute-settled',
719
+ code: 'substitute-settled',
720
+ candidateId,
721
+ // G2 applies to the settled line too: the goal and guards are the same
722
+ // evidence the synth-time line carried, parked when that line was written.
723
+ ...(takeEvidence(deps, sessionId) ?? {}),
724
+ saved_input_tokens: settled.saved_input_tokens,
725
+ cache_hit_delta: settled.cache_hit_delta,
726
+ output_tokens: settled.output_tokens,
727
+ });
728
+ }
729
+ /** Map one `usage` chunk onto the ledger's count names (appendix §7). */
730
+ function recordUsage(deps, sessionId, usage) {
731
+ if (usage === undefined || usage === null)
732
+ return;
733
+ const ledger = sessionUsage(deps, sessionId);
734
+ if (ledger === undefined)
735
+ return;
736
+ try {
737
+ ledger.request({
738
+ input: usage.inputTokens,
739
+ cacheRead: usage.cacheReadTokens ?? 0,
740
+ output: usage.outputTokens,
741
+ });
742
+ }
743
+ catch {
744
+ // A foreign ledger can only cost a measurement.
745
+ }
746
+ }
747
+ /**
748
+ * Store the plan a real response carried, or drop the old one when it carried
749
+ * none.
750
+ *
751
+ * The protocol tells the model to omit the block when unsure, so a response
752
+ * that does not contain a valid plan is also the model withdrawing the previous
753
+ * one. Keeping the old plan would let it fire against a much later receipt the
754
+ * model never wrote it for. A malformed block is likewise not a plan.
755
+ */
756
+ function rememberPlan(deps, sessionId, text) {
757
+ if (sessionId === undefined)
758
+ return;
759
+ try {
760
+ const plans = deps.plans;
761
+ if (plans == null || typeof plans.set !== 'function')
762
+ return;
763
+ const parsed = text.length === 0 ? { error: 'no-plan' } : parsePlan(text);
764
+ if ('plan' in parsed)
765
+ plans.set(sessionId, parsed.plan);
766
+ else
767
+ plans.delete(sessionId);
768
+ }
769
+ catch {
770
+ // A plan that cannot be stored only costs a later decision.
771
+ }
772
+ }
773
+ /**
774
+ * Abandon the pending entry: settle the mark, drop what the decision owned and
775
+ * write the reset receipt that explains it.
776
+ */
777
+ async function applyAbandon(deps, sessionId, abandon) {
778
+ settleDiscarded(deps, sessionId);
779
+ if (abandon.clearQueue)
780
+ clearPending(deps, sessionId);
781
+ if (abandon.clearAnchors)
782
+ clearAnchors(deps, sessionId);
783
+ // A plan that produced this abandoned decision must not survive to drive a
784
+ // later receipt, for either reset kind (and for the non-reset abandons too).
785
+ clearPlan(deps, sessionId);
786
+ if (abandon.reset === undefined)
787
+ return;
788
+ await appendReceipt(deps, {
789
+ version: 1,
790
+ ts: new Date().toISOString(),
791
+ sessionId,
792
+ turn: abandon.reset.turn,
793
+ stepId: abandon.reset.stepId,
794
+ kind: 'reset',
795
+ code: abandon.reset.code,
796
+ tool: abandon.entry.name,
797
+ callId: abandon.entry.callId,
798
+ candidateId: abandon.entry.candidateId,
799
+ });
800
+ }
801
+ /**
802
+ * The ordinary turn: observe the real stream.
803
+ *
804
+ * `next()` has already been called by the hook body, so the upstream iterable
805
+ * exists before the generator starts. Usage is mapped and a pending mark is
806
+ * settled at the `usage` chunk (which the host emits before `finish`); text is
807
+ * accumulated for `parsePlan`. A consumer that cancels the stream never reaches
808
+ * the plan store, because the code after the loop only runs on normal
809
+ * completion.
810
+ */
811
+ async function* observeBranch(deps, sessionId, upstream) {
812
+ let text = '';
813
+ for await (const chunk of upstream) {
814
+ if (chunk?.type === 'text-delta' && typeof chunk.text === 'string')
815
+ text += chunk.text;
816
+ if (chunk?.type === 'usage' && sessionId !== undefined) {
817
+ recordUsage(deps, sessionId, chunk.usage);
818
+ await settlePendingMark(deps, sessionId);
819
+ }
820
+ yield chunk;
821
+ }
822
+ // The host emits `usage` before `finish`, so this is normally a no-op; a
823
+ // route that omits the chunk still ends the request, and the mark must be
824
+ // consumed there rather than attributed to a later request (`'unknown'`,
825
+ // which status does not count).
826
+ if (sessionId !== undefined)
827
+ await settlePendingMark(deps, sessionId);
828
+ rememberPlan(deps, sessionId, text);
829
+ }
830
+ /**
831
+ * The synthesized turn.
832
+ *
833
+ * The plugin answers instead of the model, so `upstream` is only a fallback:
834
+ * the hook body resolved it synchronously at the waterfall point, before this
835
+ * generator runs, and it stays untouched when the entry is still live. The
836
+ * entry is re-read with `peek` (never `take`) so it survives to
837
+ * `tools/execute`; if it vanished between the synchronous decision and the
838
+ * first generator step, the mark is discarded and the real model answers,
839
+ * because a substitution that cannot be dispatched must not be faked.
840
+ *
841
+ * `upstream` is absent only when the host's `next()` itself threw while the
842
+ * hook body was resolving it; a host that cannot produce an upstream has no
843
+ * fallback to offer, so the vanished entry ends with an empty stream rather
844
+ * than a synthesized call no dispatch can check.
845
+ */
846
+ async function* synthesizeBranch(deps, sessionId, entry, upstream) {
847
+ const current = peekPending(deps, sessionId);
848
+ if (current === undefined || current.callId !== entry.callId) {
849
+ settleDiscarded(deps, sessionId);
850
+ if (upstream !== undefined)
851
+ yield* observeBranch(deps, sessionId, upstream);
852
+ return;
853
+ }
854
+ markSubstitutedFor(deps, sessionId, current.candidateId);
855
+ // Park the plan evidence for the settled line, which runs at the next real
856
+ // request after this entry has left the queue.
857
+ const evidence = current.evidence;
858
+ if (evidence !== undefined)
859
+ rememberEvidence(deps, sessionId, evidence);
860
+ await appendSubstituteReceipt(deps, sessionId, current);
861
+ yield* synthesizeTurn(current);
862
+ }
863
+ // ---------------------------------------------------------------------------
864
+ // The exported hook and session-end cleanup
865
+ // ---------------------------------------------------------------------------
866
+ /**
867
+ * Answer a pass decision: abandon what the decision owned, then observe the
868
+ * real stream.
869
+ *
870
+ * `upstream` is resolved by the hook body at the waterfall point; the generator
871
+ * only delays effects and consumption.
872
+ */
873
+ function observedPass(deps, plan, upstream) {
874
+ return (async function* () {
875
+ if (plan.sessionId !== undefined) {
876
+ // Order matters only for evidence: the discard drops the parked
877
+ // plan/guards, and `applyAbandon` then clears the rest. Both settle
878
+ // calls are idempotent.
879
+ if (plan.discardMark === true)
880
+ settleDiscarded(deps, plan.sessionId);
881
+ if (plan.abandon !== undefined)
882
+ await applyAbandon(deps, plan.sessionId, plan.abandon);
883
+ }
884
+ yield* observeBranch(deps, plan.sessionId, upstream);
885
+ })();
886
+ }
887
+ /**
888
+ * Build the `llm/stream` listener.
889
+ *
890
+ * Returns a **synchronous** function returning an `AsyncIterable`; see the
891
+ * module header for why an `async` function here breaks every request. Any
892
+ * `purpose`-tagged call (selector, compaction, session-title) returns `next()`
893
+ * untouched: never observed, never substituted. Every real request is decided
894
+ * synchronously by {@link resolveStreamPlan} and then answered by a generator.
895
+ *
896
+ * The upstream iterator is resolved **at the waterfall point on every path**,
897
+ * before any generator body runs. The host's terminal is a lazy async iterable
898
+ * (starting it is what calls the model), so resolving it on the synthesis path
899
+ * costs nothing; it is only consumed if the pending entry vanished and the real
900
+ * model has to answer. Resolving it lazily inside the generator would resume a
901
+ * waterfall the host may already have moved past.
902
+ */
903
+ export function streamHook(deps) {
904
+ return (options, next) => {
905
+ // Any purpose-tagged request is auxiliary (appendix §1): the selector, the
906
+ // compaction summarizer, the session-title model. They share the session
907
+ // id but are not conversation steps, so they pass through raw: no
908
+ // substitution, no usage observation, no settlement, no plan rollover.
909
+ if (options?.purpose !== undefined)
910
+ return next();
911
+ const sessionId = sessionIdOf(options);
912
+ if (sessionId !== undefined) {
913
+ const turn = clockTurnOf(deps, sessionId);
914
+ if (turn !== undefined) {
915
+ let rolledOver = false;
916
+ try {
917
+ rolledOver = deps.sessions?.notePlanTurn(sessionId, turn) === true;
918
+ }
919
+ catch {
920
+ rolledOver = false;
921
+ }
922
+ if (rolledOver)
923
+ clearPlan(deps, sessionId);
924
+ }
925
+ }
926
+ let plan;
927
+ try {
928
+ plan = resolveStreamPlan(deps, options);
929
+ }
930
+ catch {
931
+ // A bug in our own decision logic must not take the model request down,
932
+ // but it must still take the ordinary pass path: the decision-time mark
933
+ // has to be discarded here or this real request would settle a
934
+ // substitution that never ran. Clearing the queue is the same fail-closed
935
+ // answer — no decision was made.
936
+ try {
937
+ plan = passPlan(deps, sessionId, { clearQueue: true, clearAnchors: false }, true);
938
+ }
939
+ catch {
940
+ plan = { kind: 'pass', sessionId, discardMark: true };
941
+ }
942
+ }
943
+ // Resolve the upstream iterator before any branch. The real host's terminal
944
+ // is an async generator, so this starts no model call; it only fixes which
945
+ // request the fallbacks observe. A host whose `next()` throws was already
946
+ // failing on the pass path, so that throw is preserved there; the synthesis
947
+ // path proceeds without a fallback instead.
948
+ // Count a synthesis decision before the generator runs: an unconsumed
949
+ // stream or a vanished entry must still not let the same step be
950
+ // synthesized twice. This runs before `next()` too, so a host whose
951
+ // terminal throws cannot reopen the same step.
952
+ if (plan.kind === 'synthesize') {
953
+ const turn = clockTurnOf(deps, plan.sessionId) ?? turnNumberOf(plan.entry.turn);
954
+ recordSynthesis(deps, plan.sessionId, turn, plan.entry.callId);
955
+ }
956
+ let upstream;
957
+ try {
958
+ upstream = next();
959
+ }
960
+ catch (error) {
961
+ if (plan.kind !== 'synthesize')
962
+ throw error;
963
+ return synthesizeBranch(deps, plan.sessionId, plan.entry, undefined);
964
+ }
965
+ if (plan.kind === 'synthesize') {
966
+ return synthesizeBranch(deps, plan.sessionId, plan.entry, upstream);
967
+ }
968
+ return observedPass(deps, plan, upstream);
969
+ };
970
+ }
971
+ /**
972
+ * Drop every per-session trace the plugin keeps for `sessionId`.
973
+ *
974
+ * This is the session-end cleanup `src/index.ts` calls from its
975
+ * `session/disposed` listener: the receipt/dispatch store ships its own
976
+ * `clear`, but it does not own the queue, the anchors, the plan map or the
977
+ * per-session runtime, so the caller would otherwise have to know four separate
978
+ * clears. A pending usage mark is settled first so a mark cannot outlive the
979
+ * session it belongs to.
980
+ */
981
+ export function clearSession(deps, sessionId) {
982
+ settleDiscarded(deps, sessionId);
983
+ clearPending(deps, sessionId);
984
+ clearAnchors(deps, sessionId);
985
+ clearPlan(deps, sessionId);
986
+ forgetSynthesis(deps, sessionId);
987
+ try {
988
+ // Projection locators are session-scoped evidence: a disposed session must
989
+ // not leave its spill paths behind for the next session id to inherit.
990
+ deps.retrievals?.clear(sessionId);
991
+ }
992
+ catch {
993
+ // Same: each clear is independent.
994
+ }
995
+ try {
996
+ deps.sessionState?.clear(sessionId);
997
+ }
998
+ catch {
999
+ // Same: each clear is independent.
1000
+ }
1001
+ try {
1002
+ deps.sessions?.clear(sessionId);
1003
+ }
1004
+ catch {
1005
+ // Same.
1006
+ }
1007
+ }
1008
+ //# sourceMappingURL=llm-stream.js.map