@cltec/pi-splash-stats 0.0.0-stage → 0.1.1
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/CHANGELOG.md +62 -0
- package/LICENSE +190 -0
- package/README.md +196 -2
- package/package.json +31 -4
- package/src/discovery.ts +170 -0
- package/src/fetch-observer.ts +337 -0
- package/src/format.ts +106 -0
- package/src/identity.ts +77 -0
- package/src/index.ts +393 -0
- package/src/progress.ts +303 -0
- package/src/transport.ts +45 -0
- package/src/ui.ts +173 -0
package/src/index.ts
ADDED
|
@@ -0,0 +1,393 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pi adapter for pi-splash-stats (SPECIFICATION.md).
|
|
3
|
+
*
|
|
4
|
+
* Thin wiring only: TUI-mode gating, lifecycle, discovery, request
|
|
5
|
+
* enrichment, stream observation, and UI ownership. All statistics math is
|
|
6
|
+
* pure (identity, discovery, progress, format, transport, ui,
|
|
7
|
+
* fetch-observer modules).
|
|
8
|
+
*
|
|
9
|
+
* Chat requests use the provider hooks (`before_provider_request`,
|
|
10
|
+
* `provider_stream_event`) as the source of truth. Compaction and
|
|
11
|
+
* branch-summary requests do NOT fire those hooks (ADR 0002), so a scoped
|
|
12
|
+
* global-fetch observer (src/fetch-observer.ts) observes and enriches them.
|
|
13
|
+
* The observer passes chat traffic through untouched, so nothing is
|
|
14
|
+
* double-counted.
|
|
15
|
+
*
|
|
16
|
+
* In print, JSON, and RPC modes the extension performs no discovery, no
|
|
17
|
+
* enrichment, installs no observer, and no UI of any kind (SPEC 8.4).
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
21
|
+
|
|
22
|
+
import { DiscoveryCache, type AuthContext } from "./discovery.ts";
|
|
23
|
+
import { generationLine, prefillLine } from "./format.ts";
|
|
24
|
+
import { normalizeEndpoint, type CandidateModel } from "./identity.ts";
|
|
25
|
+
import {
|
|
26
|
+
applyOutputChunk,
|
|
27
|
+
applyTimings,
|
|
28
|
+
applyUsage,
|
|
29
|
+
applyProgress,
|
|
30
|
+
createRequestState,
|
|
31
|
+
estimateTokens,
|
|
32
|
+
isOutputChunk,
|
|
33
|
+
validateProgress,
|
|
34
|
+
type RequestState,
|
|
35
|
+
} from "./progress.ts";
|
|
36
|
+
import { enrichPayload, isPlainObject, matchesStreamRequest } from "./transport.ts";
|
|
37
|
+
import { installFetchObserver, baseUrlFromRequestUrl } from "./fetch-observer.ts";
|
|
38
|
+
import { UiController } from "./ui.ts";
|
|
39
|
+
|
|
40
|
+
/** The foreground operation that owns the display (SPEC 9, 10.2). */
|
|
41
|
+
type Phase = "chat" | "compaction" | "branch";
|
|
42
|
+
|
|
43
|
+
interface ModelLike {
|
|
44
|
+
id: string;
|
|
45
|
+
baseUrl?: string;
|
|
46
|
+
headers?: Record<string, string>;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export default function extension(pi: ExtensionAPI): void {
|
|
50
|
+
const state = {
|
|
51
|
+
/** Increments on every session_start; identifies the runtime/session. */
|
|
52
|
+
runtimeGeneration: 0,
|
|
53
|
+
/** Increments on session_start and model_select; guards in-flight work. */
|
|
54
|
+
selectionGeneration: 0,
|
|
55
|
+
/** The single active chat request (provider hooks), or null. */
|
|
56
|
+
activeRequest: null as RequestState | null,
|
|
57
|
+
/** The request the turn/agent safety net may finalize (SPEC 9). */
|
|
58
|
+
armedRequest: null as RequestState | null,
|
|
59
|
+
/** The in-flight summary request (fetch observer), or null. */
|
|
60
|
+
summaryRequest: null as RequestState | null,
|
|
61
|
+
/** The foreground operation owning the display. */
|
|
62
|
+
phase: "chat" as Phase,
|
|
63
|
+
ui: null as UiController | null,
|
|
64
|
+
discovery: new DiscoveryCache(),
|
|
65
|
+
/** Dispose function for the installed fetch observer, or null. */
|
|
66
|
+
observer: null as (() => void) | null,
|
|
67
|
+
/** Current context (model, registry) for the observer's classification. */
|
|
68
|
+
ctx: null as ExtensionContext | null,
|
|
69
|
+
/** True after session_shutdown; the state is inert until a new session. */
|
|
70
|
+
disposed: false,
|
|
71
|
+
};
|
|
72
|
+
|
|
73
|
+
const resolveAuth = (ctx: ExtensionContext, model: ModelLike): Promise<AuthContext> => {
|
|
74
|
+
const registry = ctx.modelRegistry;
|
|
75
|
+
if (!registry || typeof registry.getApiKeyAndHeaders !== "function") {
|
|
76
|
+
return Promise.resolve({ apiKey: undefined, headers: model.headers });
|
|
77
|
+
}
|
|
78
|
+
return registry
|
|
79
|
+
.getApiKeyAndHeaders(model as never)
|
|
80
|
+
.then((auth) =>
|
|
81
|
+
auth.ok
|
|
82
|
+
? { apiKey: auth.apiKey, headers: { ...(model.headers ?? {}), ...(auth.headers ?? {}) } }
|
|
83
|
+
: { apiKey: undefined, headers: model.headers },
|
|
84
|
+
)
|
|
85
|
+
.catch(() => ({ apiKey: undefined, headers: model.headers }));
|
|
86
|
+
};
|
|
87
|
+
|
|
88
|
+
const ensureUi = (ctx: ExtensionContext): UiController | null => {
|
|
89
|
+
if (ctx.mode !== "tui" || !ctx.ui) return null;
|
|
90
|
+
if (!state.ui) {
|
|
91
|
+
state.ui = new UiController({
|
|
92
|
+
setWorkingMessage: (message) => ctx.ui.setWorkingMessage(message),
|
|
93
|
+
setWidget: (key, content) => ctx.ui.setWidget(key, content),
|
|
94
|
+
});
|
|
95
|
+
}
|
|
96
|
+
return state.ui;
|
|
97
|
+
};
|
|
98
|
+
|
|
99
|
+
const startDiscovery = (ctx: ExtensionContext, model: { api?: string; baseUrl?: string; id?: string } | undefined): void => {
|
|
100
|
+
if (state.disposed || !model) return;
|
|
101
|
+
void state.discovery
|
|
102
|
+
.ensure(model, () => resolveAuth(ctx, model as ModelLike))
|
|
103
|
+
.catch(() => false);
|
|
104
|
+
};
|
|
105
|
+
|
|
106
|
+
const clearOwnedUi = (): void => {
|
|
107
|
+
state.ui?.clearAll();
|
|
108
|
+
};
|
|
109
|
+
|
|
110
|
+
const isTui = (ctx: ExtensionContext): boolean => ctx.mode === "tui";
|
|
111
|
+
|
|
112
|
+
/** Finalize a chat request exactly once and release UI ownership (SPEC 9). */
|
|
113
|
+
const finalizeRequest = (request: RequestState): void => {
|
|
114
|
+
if (request.finalized) return;
|
|
115
|
+
request.finalized = true;
|
|
116
|
+
if (state.activeRequest === request) state.activeRequest = null;
|
|
117
|
+
clearOwnedUi();
|
|
118
|
+
if (state.armedRequest === request) state.armedRequest = null;
|
|
119
|
+
};
|
|
120
|
+
|
|
121
|
+
/** Finalize the in-flight summary request (if any) and clear its UI. */
|
|
122
|
+
const finalizeSummaryRequest = (): void => {
|
|
123
|
+
const request = state.summaryRequest;
|
|
124
|
+
if (request && !request.finalized) request.finalized = true;
|
|
125
|
+
state.summaryRequest = null;
|
|
126
|
+
clearOwnedUi();
|
|
127
|
+
};
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* Shared frame processing for chat (provider hook) and summary (fetch
|
|
131
|
+
* observer) streams (SPEC 7). `widgetPrefill` selects the prefill surface:
|
|
132
|
+
* the working message for chat, the above-editor widget for summaries
|
|
133
|
+
* (SPEC 8.1). Returns true when the request's final data arrived.
|
|
134
|
+
*/
|
|
135
|
+
const renderProgressFrame = (request: RequestState, data: Record<string, unknown>, widgetPrefill: boolean): boolean => {
|
|
136
|
+
const ui = state.ui;
|
|
137
|
+
if (!ui) return false;
|
|
138
|
+
const showPrefill = (line: string | null): void => (widgetPrefill ? ui.showPrefillWidget(line) : ui.showPrefill(line));
|
|
139
|
+
|
|
140
|
+
if (data.prompt_progress !== undefined) {
|
|
141
|
+
const sample = validateProgress(data.prompt_progress);
|
|
142
|
+
if (sample) {
|
|
143
|
+
const snap = applyProgress(request.prefill, sample);
|
|
144
|
+
if (snap) {
|
|
145
|
+
request.prefillSnap = snap;
|
|
146
|
+
showPrefill(prefillLine(snap));
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
if (isOutputChunk(data)) {
|
|
152
|
+
applyOutputChunk(request.generation, data);
|
|
153
|
+
request.generationStarted = true;
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
const hasTimings = data.timings !== undefined;
|
|
157
|
+
const hasUsage = data.usage !== undefined;
|
|
158
|
+
let finished = false;
|
|
159
|
+
if (Array.isArray(data.choices) && data.choices.length > 0) {
|
|
160
|
+
const choice = data.choices[0];
|
|
161
|
+
if (isPlainObject(choice) && choice.finish_reason !== null && choice.finish_reason !== undefined) {
|
|
162
|
+
finished = true;
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
if (hasTimings) applyTimings(request.generation, data.timings);
|
|
166
|
+
if (hasUsage) applyUsage(request.generation, data.usage);
|
|
167
|
+
|
|
168
|
+
if (hasTimings || hasUsage || finished) {
|
|
169
|
+
// Final exact counts/rates may appear on the active line before cleanup.
|
|
170
|
+
if (request.generationStarted) {
|
|
171
|
+
const gen = request.generation;
|
|
172
|
+
ui.showGeneration(generationLine({ count: estimateTokens(gen), exact: gen.exact !== null, rate: gen.genRate }));
|
|
173
|
+
}
|
|
174
|
+
return true;
|
|
175
|
+
}
|
|
176
|
+
if (request.generationStarted) {
|
|
177
|
+
const gen = request.generation;
|
|
178
|
+
ui.showGeneration(generationLine({ count: estimateTokens(gen), exact: gen.exact !== null, rate: gen.genRate }));
|
|
179
|
+
}
|
|
180
|
+
return false;
|
|
181
|
+
};
|
|
182
|
+
|
|
183
|
+
/**
|
|
184
|
+
* Decide whether a fetch is an owned summary request (SPEC 10.2). Returns
|
|
185
|
+
* the caller-owned RequestState (attribution) or null to pass through. The
|
|
186
|
+
* summary is evaluated against the backend it actually uses (endpoint +
|
|
187
|
+
* model via the identity/discovery modules) — chat's eligibility proof is
|
|
188
|
+
* not reused.
|
|
189
|
+
*/
|
|
190
|
+
const classifySummary = async (url: string, method: string, body: unknown): Promise<RequestState | null> => {
|
|
191
|
+
if (state.disposed) return null;
|
|
192
|
+
if (state.phase !== "compaction" && state.phase !== "branch") return null;
|
|
193
|
+
if (method !== "POST") return null;
|
|
194
|
+
if (!isPlainObject(body)) return null;
|
|
195
|
+
const modelId = body.model;
|
|
196
|
+
if (typeof modelId !== "string" || modelId === "") return null;
|
|
197
|
+
const base = baseUrlFromRequestUrl(url);
|
|
198
|
+
if (base === null) return null;
|
|
199
|
+
const endpoint = normalizeEndpoint(base);
|
|
200
|
+
if (endpoint === null) return null;
|
|
201
|
+
const ctx = state.ctx;
|
|
202
|
+
if (!ctx) return null;
|
|
203
|
+
const candidate: CandidateModel = {
|
|
204
|
+
api: "openai-completions",
|
|
205
|
+
baseUrl: base,
|
|
206
|
+
id: modelId,
|
|
207
|
+
provider: ctx.model?.provider ?? "",
|
|
208
|
+
};
|
|
209
|
+
const owned = await state.discovery.ensure(candidate, () => resolveAuth(ctx, candidate));
|
|
210
|
+
if (!owned) return null;
|
|
211
|
+
const request = createRequestState(
|
|
212
|
+
state.runtimeGeneration,
|
|
213
|
+
state.selectionGeneration,
|
|
214
|
+
endpoint,
|
|
215
|
+
modelId,
|
|
216
|
+
ctx.model?.provider ?? "",
|
|
217
|
+
"openai-completions",
|
|
218
|
+
);
|
|
219
|
+
state.summaryRequest = request;
|
|
220
|
+
return request;
|
|
221
|
+
};
|
|
222
|
+
|
|
223
|
+
/** Install at most one fetch observer per runtime (SPEC 10.2). */
|
|
224
|
+
const installObserver = (): void => {
|
|
225
|
+
if (state.observer !== null) return;
|
|
226
|
+
state.observer = installFetchObserver<RequestState>({
|
|
227
|
+
target: globalThis,
|
|
228
|
+
classify: (url, method, body) => classifySummary(url, method, body),
|
|
229
|
+
enrich: (body, attr) => enrichPayload(body, attr.modelId) ?? body,
|
|
230
|
+
onFrame: (attr, frame) => {
|
|
231
|
+
if (state.disposed || attr.finalized || !state.ui) return;
|
|
232
|
+
const finished = renderProgressFrame(attr, frame, true);
|
|
233
|
+
if (finished) finalizeSummaryRequest();
|
|
234
|
+
},
|
|
235
|
+
onFinalize: (attr) => {
|
|
236
|
+
if (state.disposed) return;
|
|
237
|
+
if (attr === state.summaryRequest) finalizeSummaryRequest();
|
|
238
|
+
},
|
|
239
|
+
});
|
|
240
|
+
};
|
|
241
|
+
|
|
242
|
+
pi.on("session_start", (_event, ctx) => {
|
|
243
|
+
if (!isTui(ctx)) return;
|
|
244
|
+
// Session replacement/reload discards all results (SPEC 5.3/9).
|
|
245
|
+
state.runtimeGeneration += 1;
|
|
246
|
+
state.selectionGeneration += 1;
|
|
247
|
+
state.activeRequest = null;
|
|
248
|
+
state.armedRequest = null;
|
|
249
|
+
state.summaryRequest = null;
|
|
250
|
+
state.phase = "chat";
|
|
251
|
+
clearOwnedUi(); // release UI owned by the previous session
|
|
252
|
+
state.ui = null;
|
|
253
|
+
state.ctx = ctx;
|
|
254
|
+
state.disposed = false;
|
|
255
|
+
// Fresh discovery cache per session: discard all identity results (SPEC 5.3/9).
|
|
256
|
+
state.discovery.dispose();
|
|
257
|
+
state.discovery = new DiscoveryCache();
|
|
258
|
+
startDiscovery(ctx, ctx.model);
|
|
259
|
+
installObserver();
|
|
260
|
+
});
|
|
261
|
+
|
|
262
|
+
pi.on("model_select", (event, ctx) => {
|
|
263
|
+
if (!isTui(ctx)) return;
|
|
264
|
+
state.selectionGeneration += 1;
|
|
265
|
+
state.ctx = ctx;
|
|
266
|
+
if (state.activeRequest) finalizeRequest(state.activeRequest);
|
|
267
|
+
state.armedRequest = null; // a generation bump invalidates the safety-net target
|
|
268
|
+
finalizeSummaryRequest();
|
|
269
|
+
clearOwnedUi();
|
|
270
|
+
startDiscovery(ctx, event.model ?? ctx.model);
|
|
271
|
+
});
|
|
272
|
+
|
|
273
|
+
pi.on("before_provider_request", (event, ctx) => {
|
|
274
|
+
if (!isTui(ctx)) return;
|
|
275
|
+
state.phase = "chat";
|
|
276
|
+
const model = ctx.model;
|
|
277
|
+
if (!model || model.api !== "openai-completions") return;
|
|
278
|
+
const endpoint = normalizeEndpoint(model.baseUrl ?? "");
|
|
279
|
+
if (!endpoint) return;
|
|
280
|
+
const modelId = model.id;
|
|
281
|
+
return state.discovery
|
|
282
|
+
.ensure(model, () => resolveAuth(ctx, model))
|
|
283
|
+
.then((verified) => {
|
|
284
|
+
if (state.disposed || !verified) return;
|
|
285
|
+
if (ctx.model?.id !== modelId) return; // selection changed while pending
|
|
286
|
+
const enriched = enrichPayload(event.payload, modelId);
|
|
287
|
+
if (!enriched) return;
|
|
288
|
+
if (state.activeRequest) finalizeRequest(state.activeRequest);
|
|
289
|
+
const request = createRequestState(state.runtimeGeneration, state.selectionGeneration, endpoint, modelId, model.provider, model.api);
|
|
290
|
+
state.activeRequest = request;
|
|
291
|
+
state.armedRequest = request; // this request owns the turn/agent safety net
|
|
292
|
+
ensureUi(ctx);
|
|
293
|
+
return enriched;
|
|
294
|
+
})
|
|
295
|
+
.catch(() => undefined);
|
|
296
|
+
});
|
|
297
|
+
|
|
298
|
+
// Stream attribution + progress (chat only; summaries use the fetch observer).
|
|
299
|
+
pi.on("provider_stream_event", (event, ctx) => {
|
|
300
|
+
if (!isTui(ctx)) return;
|
|
301
|
+
const request = state.activeRequest;
|
|
302
|
+
if (!request || request.finalized) return;
|
|
303
|
+
if (state.phase !== "chat") return; // a summary owns the display
|
|
304
|
+
// Reject late chunks from an older runtime/selection (SPEC 9).
|
|
305
|
+
if (request.runtimeGeneration !== state.runtimeGeneration) return;
|
|
306
|
+
if (request.selectionGeneration !== state.selectionGeneration) return;
|
|
307
|
+
if (!matchesStreamRequest(request, event)) return;
|
|
308
|
+
if (!isPlainObject(event.data)) return;
|
|
309
|
+
const ui = ensureUi(ctx);
|
|
310
|
+
if (!ui) return;
|
|
311
|
+
const finished = renderProgressFrame(request, event.data, false);
|
|
312
|
+
if (finished) finalizeRequest(request);
|
|
313
|
+
});
|
|
314
|
+
|
|
315
|
+
// --- Summary lifecycle (SPEC 9) -----------------------------------------
|
|
316
|
+
// Compaction begins: the summary request will be observed by the fetch
|
|
317
|
+
// observer. Show nothing until progress data arrives (SPEC 8.1).
|
|
318
|
+
pi.on("session_before_compact", () => {
|
|
319
|
+
if (state.disposed || !state.ctx) return;
|
|
320
|
+
state.phase = "compaction";
|
|
321
|
+
ensureUi(state.ctx);
|
|
322
|
+
});
|
|
323
|
+
|
|
324
|
+
// Compaction succeeded: clear the summary UI and reset the phase.
|
|
325
|
+
pi.on("session_compact", () => {
|
|
326
|
+
if (state.disposed) return;
|
|
327
|
+
state.phase = "chat";
|
|
328
|
+
finalizeSummaryRequest();
|
|
329
|
+
});
|
|
330
|
+
|
|
331
|
+
// Compaction failed/aborted: clear the summary UI and reset the phase.
|
|
332
|
+
pi.on("session_compact_failed", () => {
|
|
333
|
+
if (state.disposed) return;
|
|
334
|
+
state.phase = "chat";
|
|
335
|
+
finalizeSummaryRequest();
|
|
336
|
+
});
|
|
337
|
+
|
|
338
|
+
// Tree navigation: only a summary-requested navigation shows statistics.
|
|
339
|
+
pi.on("session_before_tree", (event) => {
|
|
340
|
+
if (state.disposed || !state.ctx) return;
|
|
341
|
+
if (event.preparation?.userWantsSummary) {
|
|
342
|
+
state.phase = "branch";
|
|
343
|
+
ensureUi(state.ctx);
|
|
344
|
+
}
|
|
345
|
+
});
|
|
346
|
+
|
|
347
|
+
// Tree navigation completed: clear the summary UI and reset the phase.
|
|
348
|
+
pi.on("session_tree", () => {
|
|
349
|
+
if (state.disposed) return;
|
|
350
|
+
state.phase = "chat";
|
|
351
|
+
finalizeSummaryRequest();
|
|
352
|
+
});
|
|
353
|
+
|
|
354
|
+
/**
|
|
355
|
+
* Safety-net cleanup on turn_end/agent_settled (SPEC 9): finalize the armed
|
|
356
|
+
* chat request only when it is still the active request (abrupt termination
|
|
357
|
+
* with no final chunk). Never clear a summary's UI; clear orphaned owned UI
|
|
358
|
+
* only in the chat phase when no request is in flight.
|
|
359
|
+
*/
|
|
360
|
+
const safetyNetCleanup = (ctx: ExtensionContext): void => {
|
|
361
|
+
if (!isTui(ctx) || state.disposed) return;
|
|
362
|
+
const request = state.activeRequest;
|
|
363
|
+
if (request && state.armedRequest === request && !request.finalized) {
|
|
364
|
+
if (state.phase !== "chat") return;
|
|
365
|
+
finalizeRequest(request);
|
|
366
|
+
return;
|
|
367
|
+
}
|
|
368
|
+
if (!state.activeRequest && state.phase === "chat") clearOwnedUi();
|
|
369
|
+
};
|
|
370
|
+
pi.on("turn_end", (_event, ctx) => safetyNetCleanup(ctx));
|
|
371
|
+
pi.on("agent_settled", (_event, ctx) => safetyNetCleanup(ctx));
|
|
372
|
+
|
|
373
|
+
pi.on("session_shutdown", (_event, ctx) => {
|
|
374
|
+
if (!isTui(ctx)) {
|
|
375
|
+
state.discovery.dispose();
|
|
376
|
+
return;
|
|
377
|
+
}
|
|
378
|
+
state.disposed = true;
|
|
379
|
+
state.activeRequest = null;
|
|
380
|
+
state.armedRequest = null;
|
|
381
|
+
state.summaryRequest = null;
|
|
382
|
+
state.phase = "chat";
|
|
383
|
+
clearOwnedUi();
|
|
384
|
+
// Remove the fetch observer (restores the global fetch only if it is ours).
|
|
385
|
+
if (state.observer !== null) {
|
|
386
|
+
state.observer();
|
|
387
|
+
state.observer = null;
|
|
388
|
+
}
|
|
389
|
+
state.ui?.dispose();
|
|
390
|
+
state.ui = null;
|
|
391
|
+
state.discovery.dispose();
|
|
392
|
+
});
|
|
393
|
+
}
|
package/src/progress.ts
ADDED
|
@@ -0,0 +1,303 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pure statistics math (SPECIFICATION.md section 7) and per-request state.
|
|
3
|
+
*
|
|
4
|
+
* No I/O, no timers, no Pi imports. Every validator rejects malformed input
|
|
5
|
+
* rather than coercing it, and every derived value is finite or null.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
function isNonNegativeIntegral(value: unknown): value is number {
|
|
9
|
+
return typeof value === "number" && Number.isInteger(value) && value >= 0;
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
function isFiniteNonNegative(value: unknown): value is number {
|
|
13
|
+
return typeof value === "number" && Number.isFinite(value) && value >= 0;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/** Section 7.1: validated `prompt_progress` sample. */
|
|
17
|
+
export interface ProgressSample {
|
|
18
|
+
total: number;
|
|
19
|
+
/** Explicit cache field; null when the update omitted it. */
|
|
20
|
+
cache: number | null;
|
|
21
|
+
processed: number;
|
|
22
|
+
timeMs: number;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* Validate a `prompt_progress` object. Finite, non-negative, integral token
|
|
27
|
+
* counts; `time_ms` finite non-negative. Strings and other types are
|
|
28
|
+
* rejected, never coerced. Unknown properties are ignored.
|
|
29
|
+
*/
|
|
30
|
+
export function validateProgress(raw: unknown): ProgressSample | null {
|
|
31
|
+
if (typeof raw !== "object" || raw === null) return null;
|
|
32
|
+
const sample = raw as Record<string, unknown>;
|
|
33
|
+
if (!isNonNegativeIntegral(sample.total)) return null;
|
|
34
|
+
if (!isNonNegativeIntegral(sample.processed)) return null;
|
|
35
|
+
if (sample.cache !== undefined && !isNonNegativeIntegral(sample.cache)) return null;
|
|
36
|
+
if (!isFiniteNonNegative(sample.time_ms)) return null;
|
|
37
|
+
const cache = sample.cache as number | undefined;
|
|
38
|
+
if (sample.processed > sample.total) return null;
|
|
39
|
+
if (cache !== undefined && cache > sample.processed) return null;
|
|
40
|
+
return {
|
|
41
|
+
total: sample.total,
|
|
42
|
+
cache: cache === undefined ? null : cache,
|
|
43
|
+
processed: sample.processed,
|
|
44
|
+
timeMs: sample.time_ms,
|
|
45
|
+
};
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** Bounded prefill rate/ETA state for one request (SPEC 7.2-7.3). */
|
|
49
|
+
export interface PrefillState {
|
|
50
|
+
/** Established cached prefix: explicit `cache`, else first processed. */
|
|
51
|
+
baseline: number | null;
|
|
52
|
+
total: number | null;
|
|
53
|
+
lastDone: number | null;
|
|
54
|
+
lastTime: number | null;
|
|
55
|
+
/** At most 20 valid rate samples (tokens/second). */
|
|
56
|
+
samples: number[];
|
|
57
|
+
maxPercent: number | null;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
export const MAX_RATE_SAMPLES = 20;
|
|
61
|
+
|
|
62
|
+
export function createPrefillState(): PrefillState {
|
|
63
|
+
return { baseline: null, total: null, lastDone: null, lastTime: null, samples: [], maxPercent: null };
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
export interface PrefillSnapshot {
|
|
67
|
+
percent: number;
|
|
68
|
+
/** Mean rate in tokens/second, or null when unavailable. */
|
|
69
|
+
rate: number | null;
|
|
70
|
+
/** Estimated remaining milliseconds, 0 at completion, null when unavailable. */
|
|
71
|
+
etaMs: number | null;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
function mean(values: number[]): number | null {
|
|
75
|
+
if (values.length === 0) return null;
|
|
76
|
+
const sum = values.reduce((a, b) => a + b, 0);
|
|
77
|
+
const result = sum / values.length;
|
|
78
|
+
return Number.isFinite(result) && result > 0 ? result : null;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* Section 7.2/7.3: fold one validated sample into prefill state.
|
|
83
|
+
*
|
|
84
|
+
* Returns null when the sample must be ignored (regressing counters) so the
|
|
85
|
+
* previous display survives. Incompatible total/baseline changes drop rate
|
|
86
|
+
* continuity rather than inventing it.
|
|
87
|
+
*/
|
|
88
|
+
export function applyProgress(state: PrefillState, sample: ProgressSample): PrefillSnapshot | null {
|
|
89
|
+
if (sample.cache !== null) {
|
|
90
|
+
if (state.baseline !== null && state.baseline !== sample.cache) {
|
|
91
|
+
// Baseline changed incompatibly: drop rate/ETA continuity.
|
|
92
|
+
state.samples = [];
|
|
93
|
+
state.lastDone = null;
|
|
94
|
+
state.lastTime = null;
|
|
95
|
+
}
|
|
96
|
+
state.baseline = sample.cache;
|
|
97
|
+
} else if (state.baseline === null) {
|
|
98
|
+
// Legacy update without cache: first valid processed is the baseline.
|
|
99
|
+
state.baseline = sample.processed;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
if (state.total !== null && state.total !== sample.total) {
|
|
103
|
+
state.samples = [];
|
|
104
|
+
state.lastDone = null;
|
|
105
|
+
state.lastTime = null;
|
|
106
|
+
}
|
|
107
|
+
state.total = sample.total;
|
|
108
|
+
|
|
109
|
+
const work = Math.max(0, sample.total - (state.baseline ?? 0));
|
|
110
|
+
const done = Math.min(Math.max(sample.processed - (state.baseline ?? 0), 0), work);
|
|
111
|
+
if (state.lastDone !== null && done < state.lastDone) return null;
|
|
112
|
+
|
|
113
|
+
if (state.lastTime !== null && state.lastDone !== null) {
|
|
114
|
+
if (sample.timeMs > state.lastTime && done > state.lastDone) {
|
|
115
|
+
const rate = ((done - state.lastDone) * 1000) / (sample.timeMs - state.lastTime);
|
|
116
|
+
if (Number.isFinite(rate) && rate > 0) {
|
|
117
|
+
state.samples.push(rate);
|
|
118
|
+
if (state.samples.length > MAX_RATE_SAMPLES) state.samples.shift();
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
state.lastDone = done;
|
|
122
|
+
state.lastTime = sample.timeMs;
|
|
123
|
+
} else {
|
|
124
|
+
state.lastDone = done;
|
|
125
|
+
state.lastTime = sample.timeMs;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
const rawPercent = work > 0 ? (100 * done) / work : 100;
|
|
129
|
+
const percent = Math.min(
|
|
130
|
+
100,
|
|
131
|
+
Math.max(0, Math.max(rawPercent, state.maxPercent ?? 0)),
|
|
132
|
+
);
|
|
133
|
+
state.maxPercent = percent;
|
|
134
|
+
|
|
135
|
+
const rate =
|
|
136
|
+
mean(state.samples) ??
|
|
137
|
+
(done > 0 && sample.timeMs > 0
|
|
138
|
+
? Number.isFinite((done * 1000) / sample.timeMs)
|
|
139
|
+
? (done * 1000) / sample.timeMs
|
|
140
|
+
: null
|
|
141
|
+
: null);
|
|
142
|
+
|
|
143
|
+
const remaining = work - done;
|
|
144
|
+
let etaMs: number | null;
|
|
145
|
+
if (remaining <= 0) {
|
|
146
|
+
etaMs = 0;
|
|
147
|
+
} else if (rate === null) {
|
|
148
|
+
etaMs = null;
|
|
149
|
+
} else {
|
|
150
|
+
const candidate = (remaining / rate) * 1000;
|
|
151
|
+
// Never display a fabricated 0s prediction while work remains.
|
|
152
|
+
etaMs = Number.isFinite(candidate) && candidate >= 500 ? candidate : null;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
return { percent, rate, etaMs };
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/** Section 7.4: approximate generated-output state for one request. */
|
|
159
|
+
export interface GenerationState {
|
|
160
|
+
/** Nonempty output chunks (text, reasoning, or tool fragments). */
|
|
161
|
+
chunks: number;
|
|
162
|
+
/** Output characters (text + reasoning + tool argument fragments). */
|
|
163
|
+
chars: number;
|
|
164
|
+
/** Exact final count: usage.completion_tokens, else timings.predicted_n. */
|
|
165
|
+
exact: number | null;
|
|
166
|
+
/** Authoritative final generation rate (timings only), null = unavailable. */
|
|
167
|
+
genRate: number | null;
|
|
168
|
+
/** Authoritative final prompt rate (timings only), null = unavailable. */
|
|
169
|
+
promptRate: number | null;
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
export function createGenerationState(): GenerationState {
|
|
173
|
+
return { chunks: 0, chars: 0, exact: null, genRate: null, promptRate: null };
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
function chunkFields(data: Record<string, unknown>): {
|
|
177
|
+
content: string;
|
|
178
|
+
reasoning: string;
|
|
179
|
+
toolChars: number;
|
|
180
|
+
} | null {
|
|
181
|
+
const choices = data.choices;
|
|
182
|
+
if (!Array.isArray(choices) || choices.length === 0) return null;
|
|
183
|
+
const choice = choices[0];
|
|
184
|
+
if (typeof choice !== "object" || choice === null) return null;
|
|
185
|
+
const delta = (choice as Record<string, unknown>).delta;
|
|
186
|
+
if (typeof delta !== "object" || delta === null) return null;
|
|
187
|
+
const d = delta as Record<string, unknown>;
|
|
188
|
+
const content = typeof d.content === "string" ? d.content : "";
|
|
189
|
+
const reasoning = typeof d.reasoning_content === "string" ? d.reasoning_content : "";
|
|
190
|
+
let toolChars = 0;
|
|
191
|
+
if (Array.isArray(d.tool_calls)) {
|
|
192
|
+
for (const call of d.tool_calls) {
|
|
193
|
+
if (typeof call !== "object" || call === null) continue;
|
|
194
|
+
const fn = (call as Record<string, unknown>).function;
|
|
195
|
+
if (typeof fn === "object" && fn !== null) {
|
|
196
|
+
const args = (fn as Record<string, unknown>).arguments;
|
|
197
|
+
if (typeof args === "string") toolChars += args.length;
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
return { content, reasoning, toolChars };
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
/** True when the chunk carries generated output (not role-only/keepalive). */
|
|
205
|
+
export function isOutputChunk(data: unknown): boolean {
|
|
206
|
+
if (typeof data !== "object" || data === null) return false;
|
|
207
|
+
const fields = chunkFields(data as Record<string, unknown>);
|
|
208
|
+
if (!fields) return false;
|
|
209
|
+
return fields.content.length > 0 || fields.reasoning.length > 0 || fields.toolChars > 0;
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/**
|
|
213
|
+
* Section 7.4: count one output chunk once, text and reasoning characters;
|
|
214
|
+
* tool fragments count but are never retained.
|
|
215
|
+
*/
|
|
216
|
+
export function applyOutputChunk(state: GenerationState, data: unknown): void {
|
|
217
|
+
if (typeof data !== "object" || data === null) return;
|
|
218
|
+
const fields = chunkFields(data as Record<string, unknown>);
|
|
219
|
+
if (!fields) return;
|
|
220
|
+
if (fields.content.length === 0 && fields.reasoning.length === 0 && fields.toolChars === 0) return;
|
|
221
|
+
state.chunks += 1;
|
|
222
|
+
state.chars += fields.content.length + fields.reasoning.length + fields.toolChars;
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
/** Estimated tokens until exact final data arrives (SPEC 7.4). */
|
|
226
|
+
export function estimateTokens(state: GenerationState): number {
|
|
227
|
+
if (state.exact !== null) return state.exact;
|
|
228
|
+
return Math.max(state.chunks, Math.round(state.chars / 6));
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
/** Exact count from a `usage` object; usage wins over timings. */
|
|
232
|
+
export function applyUsage(state: GenerationState, usage: unknown): void {
|
|
233
|
+
if (typeof usage !== "object" || usage === null) return;
|
|
234
|
+
const tokens = (usage as Record<string, unknown>).completion_tokens;
|
|
235
|
+
if (isNonNegativeIntegral(tokens)) state.exact = tokens;
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
/**
|
|
239
|
+
* Section 7.5: authoritative final data from `timings`. Zero rates mean
|
|
240
|
+
* unavailable, never measured zero-speed generation.
|
|
241
|
+
*/
|
|
242
|
+
export function applyTimings(state: GenerationState, timings: unknown): void {
|
|
243
|
+
if (typeof timings !== "object" || timings === null) return;
|
|
244
|
+
const t = timings as Record<string, unknown>;
|
|
245
|
+
if (isNonNegativeIntegral(t.predicted_n) && state.exact === null) state.exact = t.predicted_n;
|
|
246
|
+
if (isFiniteNonNegative(t.predicted_per_second) && t.predicted_per_second > 0) {
|
|
247
|
+
state.genRate = t.predicted_per_second;
|
|
248
|
+
}
|
|
249
|
+
if (isFiniteNonNegative(t.prompt_per_second) && t.prompt_per_second > 0) {
|
|
250
|
+
state.promptRate = t.prompt_per_second;
|
|
251
|
+
}
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
/**
|
|
255
|
+
* Per-request statistics state (SPEC 9): a unique id plus the runtime/session
|
|
256
|
+
* and selection generations captured at request start, so late, stale, or
|
|
257
|
+
* cross-runtime work can be rejected.
|
|
258
|
+
*/
|
|
259
|
+
let requestCounter = 0;
|
|
260
|
+
|
|
261
|
+
export interface RequestState {
|
|
262
|
+
id: number;
|
|
263
|
+
/** Runtime/session generation captured at request start (SPEC 9). */
|
|
264
|
+
runtimeGeneration: number;
|
|
265
|
+
/** Selection generation captured at request start (SPEC 9). */
|
|
266
|
+
selectionGeneration: number;
|
|
267
|
+
endpoint: string;
|
|
268
|
+
modelId: string;
|
|
269
|
+
provider: string;
|
|
270
|
+
api: string;
|
|
271
|
+
phase: "chat";
|
|
272
|
+
prefill: PrefillState;
|
|
273
|
+
prefillSnap: PrefillSnapshot | null;
|
|
274
|
+
generation: GenerationState;
|
|
275
|
+
generationStarted: boolean;
|
|
276
|
+
finalized: boolean;
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
export function createRequestState(
|
|
280
|
+
runtimeGeneration: number,
|
|
281
|
+
selectionGeneration: number,
|
|
282
|
+
endpoint: string,
|
|
283
|
+
modelId: string,
|
|
284
|
+
provider: string,
|
|
285
|
+
api: string,
|
|
286
|
+
): RequestState {
|
|
287
|
+
requestCounter += 1;
|
|
288
|
+
return {
|
|
289
|
+
id: requestCounter,
|
|
290
|
+
runtimeGeneration,
|
|
291
|
+
selectionGeneration,
|
|
292
|
+
endpoint,
|
|
293
|
+
modelId,
|
|
294
|
+
provider,
|
|
295
|
+
api,
|
|
296
|
+
phase: "chat",
|
|
297
|
+
prefill: createPrefillState(),
|
|
298
|
+
prefillSnap: null,
|
|
299
|
+
generation: createGenerationState(),
|
|
300
|
+
generationStarted: false,
|
|
301
|
+
finalized: false,
|
|
302
|
+
};
|
|
303
|
+
}
|