dsh-boost 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +97 -33
- package/README.md +85 -32
- package/dist/gate/decide.js +33 -2
- package/dist/gate/decide.js.map +1 -1
- package/dist/hooks/llm-stream.js +129 -54
- package/dist/hooks/llm-stream.js.map +1 -1
- package/dist/hooks/post-execute.js +104 -21
- package/dist/hooks/post-execute.js.map +1 -1
- package/dist/hooks/session-state.js +18 -8
- package/dist/hooks/session-state.js.map +1 -1
- package/dist/index.js +371 -67
- package/dist/index.js.map +1 -1
- package/dist/scope/doc.js.map +1 -1
- package/dist/scope/store.js +24 -9
- package/dist/scope/store.js.map +1 -1
- package/package.json +8 -4
- package/dist/admission/fixed-cost.d.ts +0 -23
- package/dist/admission/ledger.d.ts +0 -113
- package/dist/admission/retrieval.d.ts +0 -65
- package/dist/admission/usage.d.ts +0 -75
- package/dist/config.d.ts +0 -43
- package/dist/gate/binding.d.ts +0 -113
- package/dist/gate/decide.d.ts +0 -82
- package/dist/gate/guard.d.ts +0 -69
- package/dist/gate/invalidate.d.ts +0 -112
- package/dist/gate/plan.d.ts +0 -86
- package/dist/hooks/clock.d.ts +0 -68
- package/dist/hooks/execute.d.ts +0 -79
- package/dist/hooks/llm-stream.d.ts +0 -283
- package/dist/hooks/pending.d.ts +0 -89
- package/dist/hooks/post-execute.d.ts +0 -257
- package/dist/hooks/session-state.d.ts +0 -158
- package/dist/hooks/synthesize.d.ts +0 -74
- package/dist/host/loader.d.ts +0 -23
- package/dist/host/platform.d.ts +0 -18
- package/dist/host/root.d.ts +0 -25
- package/dist/projection/apply.d.ts +0 -174
- package/dist/projection/canonicalise.d.ts +0 -43
- package/dist/projection/counters.d.ts +0 -65
- package/dist/projection/truncate.d.ts +0 -47
- package/dist/prompt/protocol.d.ts +0 -45
- package/dist/receipts/store.d.ts +0 -198
- package/dist/scope/doc.d.ts +0 -117
- package/dist/scope/resolve.d.ts +0 -91
- package/dist/scope/store.d.ts +0 -135
- package/dist/selector/jev.d.ts +0 -93
- package/dist/tools/boost.d.ts +0 -380
- package/dist/tools/family.d.ts +0 -26
|
@@ -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;
|
package/dist/hooks/pending.d.ts
DELETED
|
@@ -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;
|
|
@@ -1,257 +0,0 @@
|
|
|
1
|
-
import type { StepBudget } from '../admission/ledger.js';
|
|
2
|
-
import type { RetrievalLedger } from '../admission/retrieval.js';
|
|
3
|
-
import type { UsageLedger } from '../admission/usage.js';
|
|
4
|
-
import type { AnchorStore } from '../gate/invalidate.js';
|
|
5
|
-
import type { Guard, Plan } from '../gate/plan.js';
|
|
6
|
-
import type { ProjectionCounters } from '../projection/counters.js';
|
|
7
|
-
import type { FormatFooter, SpillBackend } from '../projection/apply.js';
|
|
8
|
-
import type { ReceiptStore } from '../receipts/store.js';
|
|
9
|
-
import type { ScopeStore } from '../scope/store.js';
|
|
10
|
-
import type { LlmLike } from '../selector/jev.js';
|
|
11
|
-
import type { BoostConfig, PluginContext } from '../types.js';
|
|
12
|
-
import type { TurnClock } from './clock.js';
|
|
13
|
-
import { streamHook } from './llm-stream.js';
|
|
14
|
-
import type { SessionRuntime } from './llm-stream.js';
|
|
15
|
-
import type { PendingEntry, PendingQueue } from './pending.js';
|
|
16
|
-
import { ReceiptSessionState } from './session-state.js';
|
|
17
|
-
/**
|
|
18
|
-
* The `llm/stream` body lives in its own module (Task 23c-1). It is re-exported
|
|
19
|
-
* here because `registerHooks` is the assembly surface the rest of the plugin
|
|
20
|
-
* and the integration tests import; the mount below uses the same function.
|
|
21
|
-
*/
|
|
22
|
-
export { streamHook };
|
|
23
|
-
/**
|
|
24
|
-
* The substitution whitelist: exactly the read-only trio (design §5.2-5).
|
|
25
|
-
*
|
|
26
|
-
* One constant drives both `decide` (non-shadow) and the `whitelisted` field
|
|
27
|
-
* written to the shadow/substitute receipts, so the policy the gate enforced
|
|
28
|
-
* and the policy the audit trail reports cannot drift. `bash`, `web_fetch` and
|
|
29
|
-
* every write tool stay out: they have no deterministic read-only judgement.
|
|
30
|
-
*/
|
|
31
|
-
export declare const SUBSTITUTION_WHITELIST: ReadonlySet<string>;
|
|
32
|
-
/** The route an `ask-selector` request inherits from the boundary request. */
|
|
33
|
-
export interface SelectorRoute {
|
|
34
|
-
provider: string;
|
|
35
|
-
model: string;
|
|
36
|
-
reasoningEffort?: string;
|
|
37
|
-
}
|
|
38
|
-
/** The dependencies the mounts read; Task 23c constructs the whole set once. */
|
|
39
|
-
export interface HookDeps {
|
|
40
|
-
config: BoostConfig;
|
|
41
|
-
scope: ScopeStore;
|
|
42
|
-
receipts: ReceiptStore;
|
|
43
|
-
/**
|
|
44
|
-
* Per-session receipt anchors (design §5.2-7).
|
|
45
|
-
*
|
|
46
|
-
* Written by the decision path on a real commit and read here to detect an
|
|
47
|
-
* external rewrite; a hit clears them. Required by the contract: without a
|
|
48
|
-
* store the invalidation check is silently dead.
|
|
49
|
-
*/
|
|
50
|
-
anchors: AnchorStore;
|
|
51
|
-
/**
|
|
52
|
-
* Session id to workspace id.
|
|
53
|
-
*
|
|
54
|
-
* Required: substitution is refused for a session that does not resolve to a
|
|
55
|
-
* workspace, or whose live scope document does not list that workspace. The
|
|
56
|
-
* judgement cache alone can be stale, and the replacement path must never
|
|
57
|
-
* run without a current visibility answer (design §5.5). Returning
|
|
58
|
-
* `undefined` is fail-closed, never an error.
|
|
59
|
-
*/
|
|
60
|
-
resolveSession: (sessionId: string) => string | undefined;
|
|
61
|
-
/** At most one pending substitution per session; absent means the path is inert. */
|
|
62
|
-
queue?: PendingQueue;
|
|
63
|
-
/**
|
|
64
|
-
* Per-turn substitution budget; absent means no cap is applied. Used only
|
|
65
|
-
* when `sessions` is absent, so a shared instance is never preferred over
|
|
66
|
-
* the per-session runtime.
|
|
67
|
-
*/
|
|
68
|
-
budget?: StepBudget;
|
|
69
|
-
/** Usage pairing; the shared fallback when `sessions` is absent (T21/T23c). */
|
|
70
|
-
usage?: UsageLedger;
|
|
71
|
-
/**
|
|
72
|
-
* The host turn/step clock; `step()` is the only source of a call id's step.
|
|
73
|
-
* The shared fallback when `sessions` is absent.
|
|
74
|
-
*/
|
|
75
|
-
clock?: TurnClock;
|
|
76
|
-
/**
|
|
77
|
-
* Per-session clock, budget and usage (Task 23c).
|
|
78
|
-
*
|
|
79
|
-
* A shared `clock` lets another session's turn/step stamp this session's
|
|
80
|
-
* `callId`; a shared `StepBudget` starves a session; a shared `UsageLedger`
|
|
81
|
-
* pairs one session's substitution with another session's request. When
|
|
82
|
-
* supplied, this runtime is authoritative and the three single instances
|
|
83
|
-
* above are only the fallback for a plugin wired without it. 23c-2 constructs
|
|
84
|
-
* one `SessionRuntime`, drives `onModelRequest` from the host's
|
|
85
|
-
* `agent/request` payload, and passes it here.
|
|
86
|
-
*/
|
|
87
|
-
sessions?: SessionRuntime;
|
|
88
|
-
/**
|
|
89
|
-
* The host LLM service, used only for the `ask-selector` call.
|
|
90
|
-
*
|
|
91
|
-
* Optional so a minimal assembly (or a unit test of the decision path)
|
|
92
|
-
* degrades to a record-only abstention rather than crashing. The selector
|
|
93
|
-
* request carries `purpose: 'boost-selector'`, which the frozen stream hook
|
|
94
|
-
* lets through untouched (Task 23c-2).
|
|
95
|
-
*/
|
|
96
|
-
llm?: LlmLike;
|
|
97
|
-
/**
|
|
98
|
-
* The effective provider/model of the session's latest model request.
|
|
99
|
-
*
|
|
100
|
-
* The selector request must inherit the boundary request's route; this hook
|
|
101
|
-
* has no `GenerateOptions` of its own, so 23c-2 captures it from the
|
|
102
|
-
* `agent/request` waterfall and exposes it here. Missing means the selector
|
|
103
|
-
* cannot run and `ask-selector` records an abstention.
|
|
104
|
-
*/
|
|
105
|
-
selectorRoute?: (sessionId: string) => SelectorRoute | undefined;
|
|
106
|
-
/** Parsed plans per session, written by 23c's stream hook. */
|
|
107
|
-
plans?: Map<string, Plan>;
|
|
108
|
-
/**
|
|
109
|
-
* The per-session receipt/dispatch store. Optional so 23c can own the
|
|
110
|
-
* instance and call `clear(sessionId)` on a session-end signal; when omitted,
|
|
111
|
-
* `registerHooks` creates one. Lifetime: the store keeps one host turn's
|
|
112
|
-
* receipts and in-flight dispatches per session, folds them on the first call
|
|
113
|
-
* of a new turn, and otherwise retains the last turn until `clear` (or process
|
|
114
|
-
* exit). The class documents the reasoning.
|
|
115
|
-
*/
|
|
116
|
-
sessionState?: ReceiptSessionState;
|
|
117
|
-
/** The host spill backend; absent skips apply-mode projection. */
|
|
118
|
-
spill?: SpillBackend;
|
|
119
|
-
/**
|
|
120
|
-
* Session → spill locators of the receipts this plugin projected.
|
|
121
|
-
*
|
|
122
|
-
* Its only producer is a real spill write (design §5.3): the applied outcome
|
|
123
|
-
* carries the locator, and a later `read`/`grep` naming it becomes a
|
|
124
|
-
* `projection-retrieval` receipt whose cost is subtracted from the projection
|
|
125
|
-
* net. Optional so a minimal assembly degrades to uncounted retrievals rather
|
|
126
|
-
* than crashing; `apply` constructs one and `clearSession` drops a session's
|
|
127
|
-
* set on disposal.
|
|
128
|
-
*/
|
|
129
|
-
retrievals?: RetrievalLedger;
|
|
130
|
-
/**
|
|
131
|
-
* Projection skip counters (Task 25 review).
|
|
132
|
-
*
|
|
133
|
-
* `projectDecision` increments the unknown-family counter when a tool name has
|
|
134
|
-
* no configured family, so status can distinguish "no window, by design"
|
|
135
|
-
* from "the mapper missed a decorated name".
|
|
136
|
-
*/
|
|
137
|
-
projectionCounters?: ProjectionCounters;
|
|
138
|
-
/**
|
|
139
|
-
* Token estimator; absent means no meter.
|
|
140
|
-
*
|
|
141
|
-
* Projection still clips, but records `estimate:'unknown'` and no token
|
|
142
|
-
* numbers; substitution is refused before it can spend money (design §9).
|
|
143
|
-
*/
|
|
144
|
-
estimateText?: (t: string) => number;
|
|
145
|
-
/**
|
|
146
|
-
* Which estimator produced a projection receipt's numbers.
|
|
147
|
-
*
|
|
148
|
-
* `host` means the synchronous host token meter priced it. `unknown` is the
|
|
149
|
-
* only meterless value: a projection without a meter still clips, but its
|
|
150
|
-
* receipt carries `estimate:'unknown'` and no numbers at all. There is
|
|
151
|
-
* deliberately no characters-over-four arm — a fixed-density guess is not a
|
|
152
|
-
* measurement, and admitting the type would let a future producer stamp a
|
|
153
|
-
* fabricated figure as if the host had measured it.
|
|
154
|
-
*/
|
|
155
|
-
estimateKind?: 'host' | 'unknown';
|
|
156
|
-
/**
|
|
157
|
-
* The host spill-notice predicate, injected instead of imported.
|
|
158
|
-
*
|
|
159
|
-
* Kept because the host spill policy is not declared as a dependency at all and a
|
|
160
|
-
* test needs to hand over a throwing predicate without the host package.
|
|
161
|
-
* Production omits it and the dynamically imported host function is used.
|
|
162
|
-
*/
|
|
163
|
-
hasSpillNotice?: (text: string) => boolean;
|
|
164
|
-
/**
|
|
165
|
-
* The host spill footer renderer, injected instead of imported.
|
|
166
|
-
*
|
|
167
|
-
* The same seam and the same reason as {@link hasSpillNotice}: the notice
|
|
168
|
-
* module is reached by `import()` only, and a test must be able to exercise
|
|
169
|
-
* the "module absent" path (which disables apply-mode projection) without
|
|
170
|
-
* uninstalling the host package. Returning `undefined` means the module has
|
|
171
|
-
* no renderer; production omits this and the dynamically imported host
|
|
172
|
-
* function is used.
|
|
173
|
-
*/
|
|
174
|
-
resolveFooter?: () => FormatFooter | undefined | Promise<FormatFooter | undefined>;
|
|
175
|
-
/**
|
|
176
|
-
* The session's runtime replay horizon (design §5.3), when the assembly can
|
|
177
|
-
* supply it.
|
|
178
|
-
*
|
|
179
|
-
* The horizon is `min(config horizon, mean of the session's last
|
|
180
|
-
* `historyTurns` turns)`. Its instance (`RuntimeStepHorizon`) is built in
|
|
181
|
-
* `src/index.ts` and read there by `status`; the decision path can only see
|
|
182
|
-
* it through this seam. A projection receipt pins whatever this returns, so
|
|
183
|
-
* a historical saving is never re-valued by a later cross-session minimum.
|
|
184
|
-
* Absent (the current production wiring) means the resolved config's
|
|
185
|
-
* `horizonSteps` is the horizon in effect.
|
|
186
|
-
*/
|
|
187
|
-
horizonFor?: (sessionId: string) => number;
|
|
188
|
-
/**
|
|
189
|
-
* Drop the per-session dispatch mirror on disposal.
|
|
190
|
-
*
|
|
191
|
-
* `clearSession` lives in the stream hook and the mirror lives here, so the
|
|
192
|
-
* teardown reaches it through this seam rather than exporting the map. Wired
|
|
193
|
-
* by `apply`; absent in tests, which is why it is optional and guarded.
|
|
194
|
-
*/
|
|
195
|
-
clearAcceptedDispatch?: (sessionId: string) => void;
|
|
196
|
-
/**
|
|
197
|
-
* The host logger, for the few conditions that have no other surface.
|
|
198
|
-
*
|
|
199
|
-
* `registerHooks` fills it from `ctx.logger` when absent, so production never
|
|
200
|
-
* passes it explicitly. A missing footer renderer is the one current caller:
|
|
201
|
-
* it logs once, and `status` reports the same condition as a stable code.
|
|
202
|
-
*/
|
|
203
|
-
logger?: {
|
|
204
|
-
warn(message: string): void;
|
|
205
|
-
};
|
|
206
|
-
}
|
|
207
|
-
/** What a substitute, substitute-settled or shadow receipt adds about its plan. */
|
|
208
|
-
export interface SubstitutionEvidence {
|
|
209
|
-
/** The plan's goal, capped to {@link MAX_RECEIPT_PLAN_CODE_POINTS}. */
|
|
210
|
-
plan: string;
|
|
211
|
-
/** The committed candidate's guards, up to {@link MAX_RECEIPT_GUARDS}. */
|
|
212
|
-
guards: unknown[];
|
|
213
|
-
/** The plan's guard count, present only when `guards` was capped. */
|
|
214
|
-
guards_total?: number;
|
|
215
|
-
}
|
|
216
|
-
/**
|
|
217
|
-
* A queued entry carrying the evidence the synth-time receipt needs.
|
|
218
|
-
*
|
|
219
|
-
* `PendingEntry` is the one object that travels from the commit (post-execute)
|
|
220
|
-
* to synthesis (llm-stream), so the evidence rides on it; the settle afterwards
|
|
221
|
-
* reads it back from the ledger pairing. The extra field is additive and never
|
|
222
|
-
* dispatched: `synthesizeTurn` reads `name`/`args` only.
|
|
223
|
-
*/
|
|
224
|
-
export type AuditedPendingEntry = PendingEntry & {
|
|
225
|
-
evidence?: SubstitutionEvidence;
|
|
226
|
-
};
|
|
227
|
-
/**
|
|
228
|
-
* The plan/goal and guard evidence for one committed candidate.
|
|
229
|
-
*
|
|
230
|
-
* Guards are carried as written while they fit. Only a guard whose own JSON
|
|
231
|
-
* exceeds {@link MAX_RECEIPT_GUARD_CODE_POINTS} (a multi-KB `text_contains`,
|
|
232
|
-
* say) is replaced by a `truncated_json` marker, so the array stays bounded
|
|
233
|
-
* without silently dropping the guard's form.
|
|
234
|
-
*/
|
|
235
|
-
export declare function substitutionEvidence(goal: unknown, guards: readonly Guard[]): SubstitutionEvidence;
|
|
236
|
-
/** Drop the mirrored dispatch; no pending mark is waiting to settle it. */
|
|
237
|
-
export declare function clearAcceptedDispatch(deps: HookDeps, sessionId: string): void;
|
|
238
|
-
/**
|
|
239
|
-
* Register the plugin's four host integration points.
|
|
240
|
-
*
|
|
241
|
-
* The prompt section is registered first on purpose: it is the only mount that
|
|
242
|
-
* rejects a duplicate name, so a second `apply` aborts here before any event
|
|
243
|
-
* hook is mounted twice (the host turns a duplicate section into an error, and
|
|
244
|
-
* `apply` treats that as "already mounted"). Registering it last would leave
|
|
245
|
-
* three live duplicate listeners behind.
|
|
246
|
-
*
|
|
247
|
-
* One `ReceiptSessionState` belongs to the whole registration: the execute
|
|
248
|
-
* mount writes the in-flight call mapping and the post-execute mount consumes
|
|
249
|
-
* it, so the two waterfalls must share it.
|
|
250
|
-
*
|
|
251
|
-
* `scope`, `receipts`, `anchors` and `resolveSession` are required by
|
|
252
|
-
* `HookDeps`, but they are still checked at the point of use: a host wiring the
|
|
253
|
-
* plugin without one of the optional pieces still gets the four mount points,
|
|
254
|
-
* and every degraded path is fail-closed instead of throwing during
|
|
255
|
-
* registration.
|
|
256
|
-
*/
|
|
257
|
-
export declare function registerHooks(ctx: PluginContext, deps: HookDeps): void;
|