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.
- package/LICENSE +202 -0
- package/NOTICE +29 -0
- package/README.en.md +476 -0
- package/README.md +408 -2
- package/cordis.patch.yml +40 -0
- package/dist/admission/fixed-cost.d.ts +23 -0
- package/dist/admission/fixed-cost.js +61 -0
- package/dist/admission/fixed-cost.js.map +1 -0
- package/dist/admission/ledger.d.ts +113 -0
- package/dist/admission/ledger.js +176 -0
- package/dist/admission/ledger.js.map +1 -0
- package/dist/admission/retrieval.d.ts +65 -0
- package/dist/admission/retrieval.js +162 -0
- package/dist/admission/retrieval.js.map +1 -0
- package/dist/admission/usage.d.ts +75 -0
- package/dist/admission/usage.js +124 -0
- package/dist/admission/usage.js.map +1 -0
- package/dist/config.d.ts +43 -0
- package/dist/config.js +103 -0
- package/dist/config.js.map +1 -0
- package/dist/gate/binding.d.ts +113 -0
- package/dist/gate/binding.js +297 -0
- package/dist/gate/binding.js.map +1 -0
- package/dist/gate/decide.d.ts +82 -0
- package/dist/gate/decide.js +163 -0
- package/dist/gate/decide.js.map +1 -0
- package/dist/gate/guard.d.ts +69 -0
- package/dist/gate/guard.js +195 -0
- package/dist/gate/guard.js.map +1 -0
- package/dist/gate/invalidate.d.ts +112 -0
- package/dist/gate/invalidate.js +111 -0
- package/dist/gate/invalidate.js.map +1 -0
- package/dist/gate/plan.d.ts +86 -0
- package/dist/gate/plan.js +222 -0
- package/dist/gate/plan.js.map +1 -0
- package/dist/hooks/clock.d.ts +68 -0
- package/dist/hooks/clock.js +82 -0
- package/dist/hooks/clock.js.map +1 -0
- package/dist/hooks/execute.d.ts +79 -0
- package/dist/hooks/execute.js +128 -0
- package/dist/hooks/execute.js.map +1 -0
- package/dist/hooks/llm-stream.d.ts +276 -0
- package/dist/hooks/llm-stream.js +1008 -0
- package/dist/hooks/llm-stream.js.map +1 -0
- package/dist/hooks/pending.d.ts +89 -0
- package/dist/hooks/pending.js +115 -0
- package/dist/hooks/pending.js.map +1 -0
- package/dist/hooks/post-execute.d.ts +247 -0
- package/dist/hooks/post-execute.js +1776 -0
- package/dist/hooks/post-execute.js.map +1 -0
- package/dist/hooks/session-state.d.ts +158 -0
- package/dist/hooks/session-state.js +168 -0
- package/dist/hooks/session-state.js.map +1 -0
- package/dist/hooks/synthesize.d.ts +74 -0
- package/dist/hooks/synthesize.js +100 -0
- package/dist/hooks/synthesize.js.map +1 -0
- package/dist/host/loader.d.ts +23 -0
- package/dist/host/loader.js +31 -0
- package/dist/host/loader.js.map +1 -0
- package/dist/host/platform.d.ts +18 -0
- package/dist/host/platform.js +19 -0
- package/dist/host/platform.js.map +1 -0
- package/dist/host/root.d.ts +18 -0
- package/dist/host/root.js +43 -0
- package/dist/host/root.js.map +1 -0
- package/dist/index.d.ts +13 -0
- package/dist/index.js +866 -0
- package/dist/index.js.map +1 -0
- package/dist/projection/apply.d.ts +174 -0
- package/dist/projection/apply.js +137 -0
- package/dist/projection/apply.js.map +1 -0
- package/dist/projection/canonicalise.d.ts +43 -0
- package/dist/projection/canonicalise.js +43 -0
- package/dist/projection/canonicalise.js.map +1 -0
- package/dist/projection/counters.d.ts +65 -0
- package/dist/projection/counters.js +88 -0
- package/dist/projection/counters.js.map +1 -0
- package/dist/projection/truncate.d.ts +47 -0
- package/dist/projection/truncate.js +57 -0
- package/dist/projection/truncate.js.map +1 -0
- package/dist/prompt/protocol.d.ts +45 -0
- package/dist/prompt/protocol.js +56 -0
- package/dist/prompt/protocol.js.map +1 -0
- package/dist/receipts/store.d.ts +198 -0
- package/dist/receipts/store.js +734 -0
- package/dist/receipts/store.js.map +1 -0
- package/dist/scope/doc.d.ts +117 -0
- package/dist/scope/doc.js +158 -0
- package/dist/scope/doc.js.map +1 -0
- package/dist/scope/resolve.d.ts +91 -0
- package/dist/scope/resolve.js +146 -0
- package/dist/scope/resolve.js.map +1 -0
- package/dist/scope/store.d.ts +135 -0
- package/dist/scope/store.js +573 -0
- package/dist/scope/store.js.map +1 -0
- package/dist/selector/jev.d.ts +93 -0
- package/dist/selector/jev.js +171 -0
- package/dist/selector/jev.js.map +1 -0
- package/dist/tools/boost.d.ts +367 -0
- package/dist/tools/boost.js +768 -0
- package/dist/tools/boost.js.map +1 -0
- package/dist/tools/family.d.ts +26 -0
- package/dist/tools/family.js +26 -0
- package/dist/tools/family.js.map +1 -0
- package/dist/types.d.ts +113 -0
- package/dist/types.js +21 -0
- package/dist/types.js.map +1 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- 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
|