dsh-boost 0.1.1 → 0.1.3

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 (52) hide show
  1. package/README.en.md +141 -51
  2. package/README.md +115 -47
  3. package/dist/admission/usage.js +41 -7
  4. package/dist/admission/usage.js.map +1 -1
  5. package/dist/gate/decide.js +33 -2
  6. package/dist/gate/decide.js.map +1 -1
  7. package/dist/hooks/llm-stream.js +232 -58
  8. package/dist/hooks/llm-stream.js.map +1 -1
  9. package/dist/hooks/post-execute.js +206 -39
  10. package/dist/hooks/post-execute.js.map +1 -1
  11. package/dist/hooks/session-state.js +18 -8
  12. package/dist/hooks/session-state.js.map +1 -1
  13. package/dist/index.js +601 -72
  14. package/dist/index.js.map +1 -1
  15. package/dist/scope/doc.js.map +1 -1
  16. package/dist/scope/store.js +24 -9
  17. package/dist/scope/store.js.map +1 -1
  18. package/dist/tools/boost.js +82 -2
  19. package/dist/tools/boost.js.map +1 -1
  20. package/package.json +9 -5
  21. package/dist/admission/fixed-cost.d.ts +0 -23
  22. package/dist/admission/ledger.d.ts +0 -113
  23. package/dist/admission/retrieval.d.ts +0 -65
  24. package/dist/admission/usage.d.ts +0 -75
  25. package/dist/config.d.ts +0 -43
  26. package/dist/gate/binding.d.ts +0 -113
  27. package/dist/gate/decide.d.ts +0 -82
  28. package/dist/gate/guard.d.ts +0 -69
  29. package/dist/gate/invalidate.d.ts +0 -112
  30. package/dist/gate/plan.d.ts +0 -86
  31. package/dist/hooks/clock.d.ts +0 -68
  32. package/dist/hooks/execute.d.ts +0 -79
  33. package/dist/hooks/llm-stream.d.ts +0 -283
  34. package/dist/hooks/pending.d.ts +0 -89
  35. package/dist/hooks/post-execute.d.ts +0 -257
  36. package/dist/hooks/session-state.d.ts +0 -158
  37. package/dist/hooks/synthesize.d.ts +0 -74
  38. package/dist/host/loader.d.ts +0 -23
  39. package/dist/host/platform.d.ts +0 -18
  40. package/dist/host/root.d.ts +0 -25
  41. package/dist/projection/apply.d.ts +0 -174
  42. package/dist/projection/canonicalise.d.ts +0 -43
  43. package/dist/projection/counters.d.ts +0 -65
  44. package/dist/projection/truncate.d.ts +0 -47
  45. package/dist/prompt/protocol.d.ts +0 -45
  46. package/dist/receipts/store.d.ts +0 -198
  47. package/dist/scope/doc.d.ts +0 -117
  48. package/dist/scope/resolve.d.ts +0 -91
  49. package/dist/scope/store.d.ts +0 -135
  50. package/dist/selector/jev.d.ts +0 -93
  51. package/dist/tools/boost.d.ts +0 -380
  52. package/dist/tools/family.d.ts +0 -26
@@ -1,68 +0,0 @@
1
- /**
2
- * Turn clock: the host turn index and the host step index within that turn.
3
- *
4
- * A DSH turn is not one model request. `dsh-agent-loop` loops `step` and each
5
- * iteration calls `agent/request`, so a single turn contains many requests.
6
- * The clock therefore copies the host's turn number on every request and resets
7
- * its per-turn state only when that number changes: the first request of a turn
8
- * starts the turn, later requests in the same turn leave it alone. The host
9
- * supplies both numbers with each request; the clock never derives either from
10
- * a request count.
11
- *
12
- * The turn index is evidence (a receipt is keyed by `(session, turn)`) and the
13
- * host's **step index** (`step()`) is what a derived tool-call id is built
14
- * from: two substitutions of one candidate inside a turn must not share an id.
15
- * The per-turn substitution cap is not this class: it is `StepBudget`
16
- * (`admission/ledger.ts`), keyed per session by `SessionRuntime`. The class
17
- * keeps only the host's numbers; a plugin-side counter would be a second,
18
- * fabricated source of step identity and must never feed `stepId` or `callId`.
19
- *
20
- * The class is deliberately bare — no timers, no host calls, no I/O — so it is
21
- * testable without a host and cannot advance on wall time.
22
- *
23
- * One instance covers one session: two concurrent sessions sharing an instance
24
- * would mix their turn numbers. Per-session keying belongs to the caller
25
- * (`SessionRuntime` does it); this class does not guess a key. The turn index
26
- * is also clamped monotonic, so a reused instance can never move `turn()`
27
- * backwards.
28
- *
29
- * @module dsh-boost/hooks/clock
30
- */
31
- /** Copies the host turn/step; nothing is derived from a request count. */
32
- export declare class TurnClock {
33
- /** Current host turn; 0 before the first request. */
34
- private turnCount;
35
- /**
36
- * The host's step index within the current turn; 0 before the first event.
37
- *
38
- * This is the host's number, never a plugin-side count. It exists because a
39
- * derived tool-call id must be unique per step: two substitutions of one
40
- * candidate inside one turn must not share an id, or the host persists two
41
- * assistant `tool_use` blocks with one id and Anthropic-style providers
42
- * reject the request (design §5.3, T23a/T23b).
43
- */
44
- private hostStep;
45
- /**
46
- * Record one model request for `hostTurn`, optionally at `hostStep`.
47
- *
48
- * A new turn resets the host step index; another request in the same turn
49
- * leaves it alone. The host numbers are authoritative — they are copied,
50
- * never derived from a request count here.
51
- *
52
- * Non-finite turns are ignored: `NaN !== NaN`, so accepting one would set the
53
- * turn to `NaN` and reset state on every later request. Backwards turns are
54
- * ignored too, so a reused instance cannot make `turn()` decrease. The
55
- * optional `hostStep` is ignored unless finite and greater than the current
56
- * one: the host's step index advances within a turn, and letting it move
57
- * backwards would let one step's call id be reused by the next.
58
- *
59
- * Called with the turn alone (the pre-`step()` signature), the step index
60
- * stays at whatever the host last reported — it is never incremented here,
61
- * because a plugin-side count is exactly what must not become a step number.
62
- */
63
- onModelRequest(hostTurn: number, hostStep?: number): void;
64
- /** The current host turn; 0 before the first model request. */
65
- turn(): number;
66
- /** The host step index within the current turn; 0 before the first event. */
67
- step(): number;
68
- }
@@ -1,79 +0,0 @@
1
- /**
2
- * Dispatch tamper check: the call that arrived is the call that was decided.
3
- *
4
- * When the plugin substitutes a call it decides the args, then synthesizes a
5
- * turn in which the model appears to have asked for them. Between the decision
6
- * and `tools/execute` those args pass through a round trip; if what arrives
7
- * differs from what was decided, the substitution has been tampered with — by a
8
- * prompt injection, by the model rewriting its own call, or by a bug — and the
9
- * call must be refused rather than executed.
10
- *
11
- * The comparison is structural and literal, and it proves equality only for the
12
- * same tool name and the same parsed argument tree. Anything it cannot prove
13
- * equal is refused; convenience is never a reason to accept.
14
- *
15
- * @module dsh-boost/hooks/execute
16
- */
17
- /**
18
- * Whether two values are literally the same, without normalising anything.
19
- *
20
- * - Two non-objects compare with `Object.is`: `NaN` equals `NaN`, and `-0` does
21
- * not equal `0`. That is the strictest reading; the point of this function is
22
- * to refuse what it cannot prove.
23
- * - Arrays compare element by element, in order, and by length. An array never
24
- * equals a non-array.
25
- * - Objects compare their own enumerable string keys: the key sets must match
26
- * and every key's value must compare equal recursively. Key order is
27
- * irrelevant, and a key whose value is `undefined` is still a key.
28
- *
29
- * Only own enumerable string keys participate, matching the host's
30
- * "losslessly JSON-serializable parsed arguments": a plain record, an array or
31
- * a scalar is the whole domain, and a non-plain object (a `Date`, a `Map`, a
32
- * class instance) is compared by whatever own keys it exposes — a `Date`
33
- * contributes none, exactly as the key rule says.
34
- *
35
- * The walk is depth-limited rather than cycle-aware: past
36
- * {@link MAX_LITERAL_DEPTH} it answers `false`, which also terminates on a
37
- * cyclic argument tree. A pair of distinct but structurally identical cycles is
38
- * therefore refused — the guard cannot prove them equal without a cycle-aware
39
- * walk, and refusing is the correct answer.
40
- *
41
- * @param a - first value, of any shape.
42
- * @param b - second value, of any shape.
43
- * @returns whether the two values are the same literal tree.
44
- */
45
- export declare function sameLiteral(a: unknown, b: unknown): boolean;
46
- /**
47
- * Refuse a dispatch whose arrival differs from the pending substitution.
48
- *
49
- * No `pending` entry means the plugin is not substituting this call, so it has
50
- * nothing to say about it and the call proceeds. Otherwise the arriving tool
51
- * `name` must be the decided name and the arriving parsed `arguments` must be
52
- * literally equal to the decided `args`; any difference is a tampered dispatch.
53
- *
54
- * A zero-argument call can arrive with `arguments: undefined` while the pending
55
- * entry stores `{}`; `undefined` alone is normalised to `{}` so substitution is
56
- * not disabled for every zero-argument tool. `null` is a real value and is
57
- * compared as one, so it does not match `{}`.
58
- *
59
- * This function only reports the verdict: it cannot see the queue, so it never
60
- * clears the pending entry. `registerHooks` clears the queue after receiving a
61
- * `reject` (Task 23b wires the lookup and the clearing).
62
- *
63
- * @param exec - the arriving dispatch: tool name and parsed arguments.
64
- * @param pending - the decided substitution, or `undefined` when none applies.
65
- * @returns `{reject: true, code: 'dispatch-rejected'}` on any mismatch, else
66
- * `{reject: false}`.
67
- */
68
- export declare function rejectIfTampered(exec: {
69
- name: string;
70
- arguments: unknown;
71
- }, pending: {
72
- name: string;
73
- args: Record<string, unknown>;
74
- } | undefined): {
75
- reject: true;
76
- code: 'dispatch-rejected';
77
- } | {
78
- reject: false;
79
- };
@@ -1,283 +0,0 @@
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** clock 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 AFTER prompt assembly (the host assembles at
82
- * // `@deepseek-ai/dsh-agent-loop/lib/index.js:692`, then dispatches pre-step
83
- * // at `:695`), and copies the host turn/step.
84
- * ctx.on('agent/pre-step', (payload, next) => {
85
- * sessions.onModelRequest(sessionId, payload.turn, payload.step)
86
- * horizon.observe(sessionId, payload.turn, payload.step)
87
- * return next()
88
- * })
89
- *
90
- * // agent/request: deprecated, kept for what the request waterfall alone
91
- * // yields: the resolved provider/model the selector inherits (after next()),
92
- * // the async visibility warm, and a clock fallback.
93
- * ctx.on('agent/request', async (payload, next) => {
94
- * sessions.onModelRequest(sessionId, payload.turn, payload.step)
95
- * await warmVisibility(scope, registry, payload.agent, sessionId, workspaces)
96
- * const config = await next()
97
- * rememberRoute(routes, sessionId, config)
98
- * return config
99
- * })
100
- *
101
- * ctx.on('session/disposed', (session) => clearSession(deps, sessionId))
102
- * ```
103
- *
104
- * The split is intentional: `agent/pre-step` is the seam the host documents for
105
- * turn/step, while the selector's effective route is only available from the
106
- * request waterfall's resolved config. Both listeners copy the clock so a host
107
- * that drops the deprecated event still advances turns. Both record the route:
108
- * `agent/pre-step` from the captured `modelSelection` (the primary source since
109
- * row 37), and `agent/request` from the resolved config as the fallback for
110
- * hosts that only populate it there. The visibility warm is owned by the
111
- * `system-prompt/assemble` listener (also in `wireSessionEvents`), which the
112
- * host runs **before** `agent/pre-step`; `agent/request`'s call is only a
113
- * fallback. This hook sees a warm judgement only because of that assemble
114
- * listener — a cold-cache read here would reintroduce the D4 prompt
115
- * invalidation, so do not move the warm back onto the pre-step seam.
116
- *
117
- * `onModelRequest` copies the host turn/step (never a plugin count) and resets
118
- * that session's budget only when its turn changes. `notePlanTurn` is the
119
- * matching rollover for the plan store: the first real request of a new turn
120
- * drops the previous turn's plan before a new one can be parsed, so a stale
121
- * plan cannot drive a substitution in the new turn. `clearSession(deps, id)`
122
- * is the session-end cleanup: queue, anchors, plans, receipt state, the usage
123
- * mark, the runtime entry and any shared-instance loan it holds, all dropped
124
- * together (obligation 10). No map is ever handed out.
125
- *
126
- * ## Settlement (obligation 11)
127
- *
128
- * The first real request after a synthesized turn carries a `usage` chunk. The
129
- * pass-through branch maps it to `UsageLedger.request()` and, if a mark is
130
- * pending, calls `settle()` and appends `{kind:'substitute-settled'}` with the
131
- * measured counts (`'unknown'` stays `'unknown'`; it is never interpolated).
132
- * When a marked entry is abandoned (turn rollover, reset, stopped receipts,
133
- * lost visibility, an unpayable or already-synthesized step, a vanished queue
134
- * entry) the mark is settled and discarded **without** a settlement receipt: no
135
- * substitution ran, so no saving exists to report (obligation 5).
136
- *
137
- * ## Anchor detection and our own projection
138
- *
139
- * The host pruner rewrites an oversized receipt in place to
140
- * `head + PRUNE_MARKER + tail`, and apply-mode projection composes
141
- * `head line + head + spill footer + tail`. Both preserve the receipt's head
142
- * and tail, so "the anchor text is not present verbatim" alone would classify
143
- * our own projection as compaction and disable substitution whenever projection
144
- * is on. `carriesAnchor` therefore accepts the exact text, or a body holding
145
- * the anchor's head *and* tail probes **plus** one of the two rewrites' own
146
- * evidence: the prune marker (which then decides `pruned-reset`) or the
147
- * projection head line, whose `output N chars; showing first H and last T`
148
- * counts must name this anchor's length and windows. A full receipt with the
149
- * same probes but a different middle — a file edited and re-read — carries
150
- * neither, so it is a lost anchor (`compaction-reset`) rather than a
151
- * substitution against content the model no longer holds.
152
- *
153
- * Probes are measured in code points (a UTF-16 slice can split a surrogate
154
- * pair) and clamped to the smallest configured projection window, because
155
- * `resolveConfig` accepts `headChars`/`tailChars` below the probe length and a
156
- * window shorter than the probe would make our own projection look like
157
- * compaction.
158
- *
159
- * Everything here is contained: a foreign store, queue, ledger, clock or
160
- * resolver can degrade the decision, never throw out of the model request.
161
- * `resolveStreamPlan` is synchronous and writes no receipt; its only state is
162
- * the per-turn synthesis tally, and every receipt/queue effect (writes, clears,
163
- * settlement) happens inside a generator after the decision.
164
- *
165
- * @module dsh-boost/hooks/llm-stream
166
- */
167
- import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm';
168
- import { StepBudget } from '../admission/ledger.js';
169
- import { UsageLedger } from '../admission/usage.js';
170
- import { TurnClock } from './clock.js';
171
- import type { HookDeps } from './post-execute.js';
172
- /**
173
- * Per-session clock, budget and usage ledger.
174
- *
175
- * The host numbers turns and steps per session; a single instance therefore
176
- * lets one session's `agent/request` stamp another session's derived `callId`,
177
- * lets one session's `StepBudget(1)` starve the next, and pairs one session's
178
- * substitution with another session's request. The runtime keys all three by
179
- * `sessionId` and is the only place a per-session primitive is created.
180
- *
181
- * The map is private: callers get the objects, never the map, and
182
- * {@link SessionRuntime.clear} is the only way an entry leaves. `onModelRequest`
183
- * is driven by Task 23c-2 from the host's `agent/request` payload; this module
184
- * cannot see that event itself. A new turn resets that session's budget (the
185
- * budget is per-turn, not per-lifetime); a non-finite or backwards turn is
186
- * ignored by `TurnClock` and therefore resets nothing.
187
- */
188
- export declare class SessionRuntime {
189
- private readonly bySession;
190
- private readonly stepsPerTurn;
191
- constructor(stepsPerTurn?: number);
192
- /** The session's clock, created on first use. */
193
- clockFor(sessionId: string): TurnClock;
194
- /** The session's turn budget, created on first use. */
195
- budgetFor(sessionId: string): StepBudget;
196
- /** The session's usage ledger, created on first use. */
197
- usageFor(sessionId: string): UsageLedger;
198
- /**
199
- * Record one host request for a session.
200
- *
201
- * `turn`/`step` are the host's numbers, copied through `TurnClock` (which
202
- * ignores non-finite and backwards turns). A turn change is the only thing
203
- * that resets the budget: a second request in one turn must keep the spend.
204
- */
205
- onModelRequest(sessionId: string, turn: number, step?: number): void;
206
- /**
207
- * Reconcile this session's plan store with `turn`; `true` on a turn change.
208
- *
209
- * The plan lives in `HookDeps.plans` and is keyed by session only, so
210
- * without this note a turn that emits no new plan keeps the previous turn's
211
- * one, and its remaining steps can still drive a substitution. The stream
212
- * hook calls this once per **real** request (never for an auxiliary
213
- * `purpose`, which is not a conversation step) and clears the plan map when
214
- * it returns true, before that request's response could write a new plan.
215
- * The first call reports true so a seeded map cannot outlive its first
216
- * request; `clearSession` drops the note with the rest of the entry.
217
- */
218
- notePlanTurn(sessionId: string, turn: number): boolean;
219
- /** Drop everything this runtime holds for one session. */
220
- clear(sessionId: string): void;
221
- /** Number of sessions with state (not the number ever seen). */
222
- size(): number;
223
- private entry;
224
- }
225
- /**
226
- * The session's clock: the per-session runtime when wired, the shared instance
227
- * otherwise — but only for the one session that instance belongs to.
228
- *
229
- * Exported because `tools/post-execute` must resolve the *same* clock for the
230
- * turn/step it stamps into a `callId`; two copies of this precedence rule could
231
- * drift and let the decision and the stream hook disagree about one session.
232
- */
233
- export declare function sessionClock(deps: HookDeps, sessionId: string): TurnClock | undefined;
234
- /** The session's turn budget; the same precedence as {@link sessionClock}. */
235
- export declare function sessionBudget(deps: HookDeps, sessionId: string): StepBudget | undefined;
236
- /** The session's usage ledger; the same precedence as {@link sessionClock}. */
237
- export declare function sessionUsage(deps: HookDeps, sessionId: string): UsageLedger | undefined;
238
- /**
239
- * Whether the receipt store has stopped writing, fail-closed.
240
- *
241
- * A missing `stopped` (a partial store in a test or an older host) is "not
242
- * stopped", so the ordinary path is unchanged. A store that *throws* cannot
243
- * record evidence, which is exactly what stopped means.
244
- */
245
- export declare function receiptsStopped(deps: HookDeps): boolean;
246
- /**
247
- * Consume the session's usage mark without reporting a saving.
248
- *
249
- * `markSubstituted` has no unmark: a mark left behind by an abandoned entry
250
- * would make the next real request settle a substitution that never ran
251
- * (obligation 5). `settle()` here is the discard, not a measurement. The parked
252
- * plan evidence goes with the mark: nothing will ever write its receipt.
253
- */
254
- export declare function settleDiscarded(deps: HookDeps, sessionId: string): void;
255
- /**
256
- * Build the `llm/stream` listener.
257
- *
258
- * Returns a **synchronous** function returning an `AsyncIterable`; see the
259
- * module header for why an `async` function here breaks every request. Any
260
- * `purpose`-tagged call (selector, compaction, session-title) returns `next()`
261
- * untouched: never observed, never substituted. Every real request is decided
262
- * synchronously by {@link resolveStreamPlan} and then answered by a generator.
263
- *
264
- * The upstream iterator is resolved **at the waterfall point on every path**,
265
- * before any generator body runs. The host's terminal is a lazy async iterable
266
- * (starting it is what calls the model), so resolving it on the synthesis path
267
- * costs nothing; it is only consumed if the pending entry vanished and the real
268
- * model has to answer. Resolving it lazily inside the generator would resume a
269
- * waterfall the host may already have moved past.
270
- */
271
- export declare function streamHook(deps: HookDeps): (options: GenerateOptions, next: () => AsyncIterable<StreamChunk>) => AsyncIterable<StreamChunk>;
272
- /**
273
- * Drop every per-session trace the plugin keeps for `sessionId`.
274
- *
275
- * This is the session-end cleanup `src/index.ts` calls from its
276
- * `session/disposed` listener: the receipt/dispatch store ships its own
277
- * `clear`, but it does not own the queue, the anchors, the plan map or the
278
- * per-session runtime, so the caller would otherwise have to know four separate
279
- * clears. A pending usage mark is settled first so a mark cannot outlive the
280
- * session it belongs to, and the shared-instance loans this session holds are
281
- * released so a disposed owner does not refuse every later session forever.
282
- */
283
- export declare function clearSession(deps: HookDeps, sessionId: string): void;
@@ -1,89 +0,0 @@
1
- /**
2
- * One decided substitution waiting for the model turn that will carry it.
3
- *
4
- * `args` is the already-validated argument tree the tool must receive. `turn`
5
- * and `step` accept number or string because the host carries numeric indexes
6
- * while receipts often use strings; the JSON array in `callIdFor` normalises
7
- * both forms of the same value to one identity.
8
- *
9
- * Treat an entry as immutable once it is queued. The queue hands out the stored
10
- * object by reference, and mutating `args` after the decision would make the
11
- * admission receipt describe arguments different from the ones dispatched.
12
- */
13
- export interface PendingEntry {
14
- /** Id shared by the synthesized tool call and the arriving dispatch. */
15
- callId: string;
16
- /** Plan candidate this call was substituted for. */
17
- candidateId: string;
18
- /** Tool name to invoke. */
19
- name: string;
20
- /** Validated argument object; serialised once by the synthesized turn. */
21
- args: Record<string, unknown>;
22
- /** Host turn the decision belongs to (number or already-stringified form). */
23
- turn: number | string;
24
- /** Host step within `turn` (number or already-stringified form); part of the call id. */
25
- step: number | string;
26
- }
27
- /**
28
- * At most one pending substitution per session.
29
- *
30
- * `set` overwrites, because a second decision in the same session supersedes
31
- * the first: the earlier call can no longer arrive (its turn is over), and
32
- * keeping it would make the tamper check compare against a stale id. `take`
33
- * removes and returns; `peek` only reads. Clearing an absent session is a
34
- * no-op, so callers do not need to know whether a decision was parked.
35
- *
36
- * **Reference semantics.** `set` stores the caller's object and `peek`/`take`
37
- * return that same object, never a copy. Own it once queued: T23b builds the
38
- * entry from the admitted candidate and must not mutate `args` afterwards, or
39
- * the admission receipt will describe a call different from the one that runs.
40
- *
41
- * **Lifetime.** Entries leave only through `take` or `clear`; there is no
42
- * expiry timer and no session hook here. A session that aborts between
43
- * `tools/post-execute` and the next `llm/stream` therefore parks its entry for
44
- * the process lifetime, so the owning hook must `clear` at session end. Failing
45
- * to clear costs memory and nothing else: the execute hook only intervenes when
46
- * the arriving call's `callId` equals the entry's, and a call with any other id
47
- * passes through untouched, so a stale entry can neither reject an ordinary call
48
- * nor be matched by one. The parked `args` are still a leak.
49
- */
50
- export declare class PendingQueue {
51
- private readonly bySession;
52
- /** Park `e` as the pending substitution for `sessionId`, replacing any earlier entry. */
53
- set(sessionId: string, e: PendingEntry): void;
54
- /** Remove and return the pending entry for `sessionId`, if any. */
55
- take(sessionId: string): PendingEntry | undefined;
56
- /** The pending entry for `sessionId`, without removing it. */
57
- peek(sessionId: string): PendingEntry | undefined;
58
- /** Drop the pending entry for `sessionId`; an absent session is a no-op. */
59
- clear(sessionId: string): void;
60
- /** Number of sessions with a pending entry (not the number of calls ever set). */
61
- size(): number;
62
- }
63
- /**
64
- * The deterministic id for one candidate at one step of one turn in one session.
65
- *
66
- * Exactly the first 16 hex characters of
67
- * `sha256(JSON.stringify([sessionId, String(turn), String(step), candidateId]))`.
68
- * Sixteen hex characters is 64 bits, far beyond any collision a session can
69
- * produce, while keeping the id short enough to read in a receipt.
70
- *
71
- * **Encoding.** The four identity components are hashed as a JSON array, not
72
- * joined with `'/'`. With a join, `('s', '1/2', 0, 'c')` and
73
- * `('s', '1', 0, '2/c')` would hash identically: a `/` inside a component
74
- * impersonates the separator.
75
- * JSON quotes each string and delimits the elements, so no component can spill
76
- * into another. `turn` and `step` are stringified first, so the host's numeric
77
- * index and a receipt's string form of the same value name one id — the
78
- * original `number | string` normalisation is preserved.
79
- *
80
- * The array also carries `step`, which the old tuple omitted: the same
81
- * candidate committed twice in one turn must receive different ids, or the host
82
- * persists two assistant `tool_use` blocks with one id and Anthropic-style
83
- * providers reject the request.
84
- *
85
- * Stable across processes because the input is fully spelled out and the hash
86
- * is SHA-256; idempotent for the same inputs; different for a different
87
- * session, turn, step, or candidate.
88
- */
89
- export declare function callIdFor(sessionId: string, turn: string | number, step: string | number, candidateId: string): string;