@cltec/pi-splash-stats 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.
@@ -0,0 +1,337 @@
1
+ /**
2
+ * Scoped global-fetch observer for owned summary inference (SPEC 10.2).
3
+ *
4
+ * Pi's provider hooks do not fire for compaction / branch-summary requests
5
+ * (ADR 0002). This module wraps the global `fetch` to observe those SSE
6
+ * responses: it enriches eligible summary requests and parses their streams
7
+ * while forwarding bytes, order, status, headers, streaming, backpressure,
8
+ * errors, and cancellation unchanged. Chat traffic is passed through
9
+ * untouched — the provider hooks remain chat's source of truth, so nothing is
10
+ * double-counted.
11
+ *
12
+ * The pure logic (SSE parsing, request-info extraction) is separated for
13
+ * direct testing; `installFetchObserver` is the thin adapter that touches the
14
+ * global fetch and response streams. No new runtime dependency is added.
15
+ */
16
+
17
+ /** How an observed summary stream ended. */
18
+ export type FinalizeReason = "done" | "error" | "abort";
19
+
20
+ /** Maximum bytes for a pending SSE event before statistics are disabled (SPEC 10.2). */
21
+ export const MAX_EVENT_BYTES = 1024 * 1024;
22
+
23
+ /** The suffix that marks a chat-completions resource URL. */
24
+ export const CHAT_COMPLETIONS_SUFFIX = "/chat/completions";
25
+
26
+ export interface SSEParserOptions {
27
+ /** Called with the assembled `data` payload of each complete event. */
28
+ onEvent(data: string): void;
29
+ /** Called once when the pending-event byte bound is exceeded. */
30
+ onOverflow?(): void;
31
+ /** Bound for a pending event, in bytes. Defaults to MAX_EVENT_BYTES. */
32
+ maxEventBytes?: number;
33
+ }
34
+
35
+ export interface SSEParser {
36
+ /** Feed a (possibly partial) chunk of the stream. */
37
+ feed(chunk: Uint8Array): void;
38
+ /** Flush any trailing frame that lacks a final newline. */
39
+ flush(): void;
40
+ /** True once statistics for this stream are disabled (overflow). */
41
+ readonly disabled: boolean;
42
+ }
43
+
44
+ /**
45
+ * Minimal SSE line/event parser (SPEC 10.2). Handles LF and CRLF line
46
+ * endings, comment lines, multi-line `data` fields, and a per-pending-event
47
+ * byte bound. On overflow it disables statistics; the caller keeps forwarding
48
+ * the original bytes. Split multi-byte UTF-8 sequences are handled by a
49
+ * streaming TextDecoder. Unknown fields (`event:`, `id:`, `retry:`) are
50
+ * ignored. A stats-processing throw never escapes (SPEC 10.3).
51
+ */
52
+ export function createSSEParser(options: SSEParserOptions): SSEParser {
53
+ const maxEventBytes = options.maxEventBytes ?? MAX_EVENT_BYTES;
54
+ const decoder = new TextDecoder();
55
+ let buffer = "";
56
+ let dataLines: string[] = [];
57
+ let disabled = false;
58
+
59
+ const dataBytes = (): number => dataLines.reduce((n, line) => n + line.length, 0);
60
+
61
+ function overflow(): void {
62
+ if (disabled) return;
63
+ disabled = true;
64
+ buffer = "";
65
+ dataLines = [];
66
+ try {
67
+ options.onOverflow?.();
68
+ } catch {
69
+ // Overflow reporting must not affect inference.
70
+ }
71
+ }
72
+
73
+ function dispatch(): void {
74
+ if (dataLines.length === 0) return;
75
+ const data = dataLines.join("\n");
76
+ dataLines = [];
77
+ try {
78
+ options.onEvent(data);
79
+ } catch {
80
+ // A stats-processing failure must not affect inference (SPEC 10.3).
81
+ }
82
+ }
83
+
84
+ function processLine(line: string): void {
85
+ if (disabled) return;
86
+ if (line === "") {
87
+ dispatch();
88
+ return;
89
+ }
90
+ if (line.startsWith(":")) return; // comment
91
+ const colon = line.indexOf(":");
92
+ let field: string;
93
+ let value: string;
94
+ if (colon === -1) {
95
+ field = line;
96
+ value = "";
97
+ } else {
98
+ field = line.slice(0, colon);
99
+ value = line.slice(colon + 1);
100
+ if (value.startsWith(" ")) value = value.slice(1);
101
+ }
102
+ if (field !== "data") return; // ignore event:, id:, retry:, unknown
103
+ dataLines.push(value);
104
+ if (dataBytes() > maxEventBytes) overflow();
105
+ }
106
+
107
+ function feed(chunk: Uint8Array): void {
108
+ if (disabled) return;
109
+ buffer += decoder.decode(chunk, { stream: true });
110
+ let idx: number;
111
+ while ((idx = buffer.indexOf("\n")) !== -1) {
112
+ let line = buffer.slice(0, idx);
113
+ buffer = buffer.slice(idx + 1);
114
+ if (line.endsWith("\r")) line = line.slice(0, -1); // CRLF
115
+ processLine(line);
116
+ if (disabled) return;
117
+ }
118
+ // After complete lines are processed, `buffer` holds the incomplete line.
119
+ if (buffer.length > maxEventBytes) overflow();
120
+ }
121
+
122
+ function flush(): void {
123
+ if (disabled) return;
124
+ buffer += decoder.decode(); // final decoder flush
125
+ if (buffer.length > 0) {
126
+ let line = buffer;
127
+ buffer = "";
128
+ if (line.endsWith("\r")) line = line.slice(0, -1);
129
+ processLine(line);
130
+ }
131
+ dispatch();
132
+ }
133
+
134
+ return {
135
+ feed,
136
+ flush,
137
+ get disabled(): boolean {
138
+ return disabled;
139
+ },
140
+ };
141
+ }
142
+
143
+ export interface RequestInfo {
144
+ url: string | null;
145
+ method: string;
146
+ bodyText: string | null;
147
+ /** True when the input form cannot be inspected/enriched safely. */
148
+ passthrough: boolean;
149
+ }
150
+
151
+ /**
152
+ * Extract (url, method, bodyText) from the fetch input forms actually used by
153
+ * the supported Pi provider: a `string` or `URL` first argument with a string
154
+ * `init.body` (the OpenAI SDK sends `fetch(URL, { body: "<json>" })`). The
155
+ * `Request` form carries a streamed body that cannot be read without consuming
156
+ * it, so it is explicitly passed through unchanged.
157
+ */
158
+ export function extractRequestInfo(input: unknown, init?: RequestInit): RequestInfo {
159
+ const method = (init?.method ?? "GET").toUpperCase();
160
+ if (typeof input === "string") {
161
+ return { url: input, method, bodyText: typeof init?.body === "string" ? init.body : null, passthrough: false };
162
+ }
163
+ if (input instanceof URL) {
164
+ return { url: input.href, method, bodyText: typeof init?.body === "string" ? init.body : null, passthrough: false };
165
+ }
166
+ // Request form (or any other form): pass through unchanged.
167
+ return { url: null, method, bodyText: null, passthrough: true };
168
+ }
169
+
170
+ /**
171
+ * Derive the API base URL from a chat-completions request URL by stripping the
172
+ * `/chat/completions` suffix. Returns null when the URL is not a
173
+ * chat-completions resource (such requests are never owned summary traffic).
174
+ */
175
+ export function baseUrlFromRequestUrl(url: string): string | null {
176
+ if (!url.endsWith(CHAT_COMPLETIONS_SUFFIX)) return null;
177
+ return url.slice(0, -CHAT_COMPLETIONS_SUFFIX.length);
178
+ }
179
+
180
+ export interface FetchObserverOptions<T> {
181
+ /** The object whose `fetch` is wrapped (injectable for tests). */
182
+ target: { fetch: typeof fetch };
183
+ /**
184
+ * Decide whether a request is an owned summary request worth observing.
185
+ * Receives the extracted URL, HTTP method, and parsed JSON body. Returns
186
+ * caller-owned attribution, or null to pass through. May be async (e.g. to
187
+ * verify identity via discovery).
188
+ */
189
+ classify(url: string, method: string, body: unknown): T | null | Promise<T | null>;
190
+ /** Enrich an eligible request body. Must return a new object (never mutate). */
191
+ enrich?(body: Record<string, unknown>, attr: T): Record<string, unknown>;
192
+ /** Called with each parsed SSE data frame (JSON object) of an observed stream. */
193
+ onFrame?(attr: T, frame: Record<string, unknown>): void;
194
+ /** Called exactly once when an observed stream ends. */
195
+ onFinalize?(attr: T, reason: FinalizeReason): void;
196
+ }
197
+
198
+ function isPlainFrame(value: unknown): value is Record<string, unknown> {
199
+ if (typeof value !== "object" || value === null) return false;
200
+ if (Array.isArray(value)) return false;
201
+ const proto = Object.getPrototypeOf(value);
202
+ return proto === Object.prototype || proto === null;
203
+ }
204
+
205
+ /**
206
+ * Wrap `target.fetch` to observe owned summary requests (SPEC 10.2).
207
+ *
208
+ * - At most one active observer per runtime. The returned `dispose` restores
209
+ * the global fetch only if it still points to this wrapper; it never
210
+ * overwrites a wrapper installed later by another extension.
211
+ * - After disposal the wrapper is inert: it delegates to the previous fetch,
212
+ * because SDK clients may retain old fetch references.
213
+ * - Eligible requests are enriched (the body is replaced) and their SSE
214
+ * responses observed. Everything else passes through byte-for-byte.
215
+ * - Observed responses preserve bytes, order, status, headers, streaming,
216
+ * backpressure, errors, and cancellation.
217
+ */
218
+ export function installFetchObserver<T>(options: FetchObserverOptions<T>): () => void {
219
+ const previous = options.target.fetch;
220
+ let disposed = false;
221
+
222
+ function finalize(attr: T, reason: FinalizeReason): void {
223
+ try {
224
+ options.onFinalize?.(attr, reason);
225
+ } catch {
226
+ // Finalize reporting must not affect inference.
227
+ }
228
+ }
229
+
230
+ async function observe(responsePromise: Promise<Response>, attr: T): Promise<Response> {
231
+ let response: Response;
232
+ try {
233
+ response = await responsePromise;
234
+ } catch (err) {
235
+ // The request failed; report, then propagate unchanged.
236
+ finalize(attr, "error");
237
+ throw err;
238
+ }
239
+ const originalBody = response.body;
240
+ if (originalBody === null) {
241
+ finalize(attr, "done");
242
+ return response;
243
+ }
244
+ const reader = originalBody.getReader();
245
+ let finalized = false;
246
+ const end = (reason: FinalizeReason): void => {
247
+ if (finalized) return;
248
+ finalized = true;
249
+ finalize(attr, reason);
250
+ };
251
+ const parser = createSSEParser({
252
+ onEvent: (data: string) => {
253
+ if (data === "[DONE]") return;
254
+ let frame: unknown;
255
+ try {
256
+ frame = JSON.parse(data);
257
+ } catch {
258
+ return; // malformed data frame: ignore, bytes are still forwarded
259
+ }
260
+ if (isPlainFrame(frame)) {
261
+ try {
262
+ options.onFrame?.(attr, frame);
263
+ } catch {
264
+ // A stats-processing failure must not affect inference (SPEC 10.3).
265
+ }
266
+ }
267
+ },
268
+ });
269
+ const newBody = new ReadableStream<Uint8Array>({
270
+ async pull(controller: ReadableStreamDefaultController<Uint8Array>): Promise<void> {
271
+ try {
272
+ const { done, value } = await reader.read();
273
+ if (done) {
274
+ parser.flush();
275
+ controller.close();
276
+ end("done");
277
+ return;
278
+ }
279
+ parser.feed(value);
280
+ controller.enqueue(value); // forward bytes unchanged (order preserved)
281
+ } catch (err) {
282
+ end("error");
283
+ controller.error(err); // propagate the read error
284
+ }
285
+ },
286
+ cancel(reason?: unknown): Promise<void> {
287
+ end("abort");
288
+ return reader.cancel(reason as AbortReason | undefined);
289
+ },
290
+ });
291
+ return new Response(newBody, {
292
+ status: response.status,
293
+ statusText: response.statusText,
294
+ headers: response.headers,
295
+ });
296
+ }
297
+
298
+ async function handle(input: Parameters<typeof fetch>[0], init?: RequestInit): Promise<Response> {
299
+ const info = extractRequestInfo(input, init);
300
+ if (info.passthrough || info.url === null || info.bodyText === null) {
301
+ return previous(input, init);
302
+ }
303
+ let body: unknown;
304
+ try {
305
+ body = JSON.parse(info.bodyText);
306
+ } catch {
307
+ return previous(input, init);
308
+ }
309
+ let attr: T | null;
310
+ try {
311
+ attr = await options.classify(info.url, info.method, body);
312
+ } catch {
313
+ return previous(input, init);
314
+ }
315
+ if (attr === null) return previous(input, init);
316
+ const enriched = options.enrich
317
+ ? options.enrich(body as Record<string, unknown>, attr)
318
+ : (body as Record<string, unknown>);
319
+ const newInit = { ...(init as Record<string, unknown> | undefined), body: JSON.stringify(enriched) };
320
+ return observe(previous(input, newInit as RequestInit), attr);
321
+ }
322
+
323
+ const wrapper = ((input: Parameters<typeof fetch>[0], init?: RequestInit) => {
324
+ if (disposed) return previous(input, init);
325
+ return handle(input, init);
326
+ }) as typeof fetch;
327
+
328
+ options.target.fetch = wrapper;
329
+
330
+ return function dispose(): void {
331
+ if (disposed) return;
332
+ disposed = true;
333
+ if (options.target.fetch === wrapper) {
334
+ options.target.fetch = previous;
335
+ }
336
+ };
337
+ }
package/src/format.ts ADDED
@@ -0,0 +1,106 @@
1
+ /**
2
+ * Pure compact-line formatting (SPECIFICATION.md section 8.2).
3
+ *
4
+ * 20-cell bar, rounded integer percent, one-decimal rates, s / m s ETA with
5
+ * carry, compact counts, `≈` for estimates, missing segments dropped with
6
+ * their separators, narrow-width adaptation (drop ETA, then shorten the
7
+ * bar). Never emits NaN, Infinity, or unexplained placeholders.
8
+ */
9
+
10
+ export const BAR_CELLS = 20;
11
+ export const NARROW_BAR_CELLS = 10;
12
+ export const TINY_BAR_CELLS = 6;
13
+
14
+ function clamp(value: number, min: number, max: number): number {
15
+ return Math.min(max, Math.max(min, value));
16
+ }
17
+
18
+ /** Counts: <1k integers, <10k one-decimal k, larger rounded k (SPEC 8.2). */
19
+ export function formatCount(value: number): string {
20
+ if (!Number.isFinite(value) || value < 0) return "0";
21
+ if (value < 1000) return String(Math.round(value));
22
+ if (value < 10000) {
23
+ const k = Math.round((value / 1000) * 10) / 10;
24
+ return (Number.isInteger(k) ? String(k) : k.toFixed(1)) + "k";
25
+ }
26
+ return Math.round(value / 1000) + "k";
27
+ }
28
+
29
+ /** Positive finite rates only; zero and non-finite are unavailable. */
30
+ export function formatRate(rate: number | null | undefined): string | null {
31
+ if (rate === null || rate === undefined) return null;
32
+ if (!Number.isFinite(rate) || rate <= 0) return null;
33
+ return rate.toFixed(1) + " tok/s";
34
+ }
35
+
36
+ /** Rounded seconds below one minute; minutes and seconds with carry above. */
37
+ export function formatEta(ms: number | null | undefined): string | null {
38
+ if (ms === null || ms === undefined) return null;
39
+ if (!Number.isFinite(ms) || ms < 0) return null;
40
+ const seconds = Math.round(ms / 1000);
41
+ if (seconds < 60) return seconds + "s";
42
+ const minutes = Math.floor(seconds / 60);
43
+ return minutes + "m " + (seconds % 60) + "s";
44
+ }
45
+
46
+ export function formatBar(percent: number, cells: number = BAR_CELLS): string {
47
+ if (!Number.isFinite(percent)) return "░".repeat(cells);
48
+ const filled = clamp(Math.round((percent / 100) * cells), 0, cells);
49
+ return "█".repeat(filled) + "░".repeat(cells - filled);
50
+ }
51
+
52
+ export interface PrefillDisplay {
53
+ percent: number | null;
54
+ rate: number | null;
55
+ etaMs: number | null;
56
+ }
57
+
58
+ /**
59
+ * One transient prefill line. Missing segments drop with their separators;
60
+ * a valid report without a percentage renders the phase alone. Narrow
61
+ * widths drop the ETA first, then shorten the bar, keeping phase and the
62
+ * primary percentage.
63
+ */
64
+ export function prefillLine(display: PrefillDisplay | null, width: number = Number.MAX_SAFE_INTEGER): string {
65
+ if (display === null) return "Prefilling...";
66
+ const eta = formatEta(display.etaMs);
67
+ const rate = formatRate(display.rate);
68
+ const build = (cells: number, withEta: boolean, withRate: boolean): string => {
69
+ let line = "Prefilling...";
70
+ if (display.percent !== null && Number.isFinite(display.percent)) {
71
+ line += " " + formatBar(clamp(display.percent, 0, 100), cells) + " " + Math.round(clamp(display.percent, 0, 100)) + "%";
72
+ }
73
+ if (withEta && eta) line += " · " + eta;
74
+ if (withRate && rate) line += " · " + rate;
75
+ return line;
76
+ };
77
+ let line = build(BAR_CELLS, true, true);
78
+ if (line.length > width) {
79
+ line = build(BAR_CELLS, false, true);
80
+ if (line.length > width) {
81
+ line = build(NARROW_BAR_CELLS, false, true);
82
+ if (line.length > width) {
83
+ line = build(TINY_BAR_CELLS, false, true);
84
+ if (line.length > width) line = build(TINY_BAR_CELLS, false, false);
85
+ }
86
+ }
87
+ }
88
+ return line;
89
+ }
90
+
91
+ export interface GenerationDisplay {
92
+ count: number;
93
+ /** True once an exact final count replaced the estimate. */
94
+ exact: boolean;
95
+ rate: number | null;
96
+ }
97
+
98
+ /** One transient generation line; estimates are marked with `≈`. */
99
+ export function generationLine(display: GenerationDisplay, width: number = Number.MAX_SAFE_INTEGER): string {
100
+ const rate = formatRate(display.rate);
101
+ const count = display.exact ? formatCount(display.count) : "≈" + formatCount(display.count);
102
+ let line = "Generating... " + count + " tok";
103
+ if (rate) line += " · " + rate;
104
+ if (line.length > width && rate) line = "Generating... " + count + " tok";
105
+ return line;
106
+ }
@@ -0,0 +1,77 @@
1
+ /**
2
+ * Pure Splash identity rules (SPECIFICATION.md sections 5.1-5.4).
3
+ *
4
+ * No I/O, no Pi imports: URL normalization, discovery-candidate selection,
5
+ * and identity-response validation. Discovery (src/discovery.ts) owns the
6
+ * network behavior and response bounds.
7
+ */
8
+
9
+ /** Maximum bytes for an identity response body (SPEC 5.3). */
10
+ export const MAX_RESPONSE_BYTES = 1024 * 1024;
11
+
12
+ /** OpenAI-style model list response shape. */
13
+ export interface IdentityEntry {
14
+ id?: unknown;
15
+ owned_by?: unknown;
16
+ }
17
+
18
+ function isPlainObject(value: unknown): value is Record<string, unknown> {
19
+ if (typeof value !== "object" || value === null) return false;
20
+ const proto = Object.getPrototypeOf(value);
21
+ return proto === Object.prototype || proto === null;
22
+ }
23
+
24
+ /**
25
+ * Canonical endpoint identity for a configured base URL (SPEC 5.4).
26
+ *
27
+ * Preserves protocol, host, explicit port, path prefixes, query, and IPv6
28
+ * syntax; strips only semantically insignificant trailing slashes. Returns
29
+ * null for invalid URLs and non-HTTP(S) schemes.
30
+ */
31
+ export function normalizeEndpoint(baseUrl: string): string | null {
32
+ let url: URL;
33
+ try {
34
+ url = new URL(baseUrl);
35
+ } catch {
36
+ return null;
37
+ }
38
+ if (url.protocol !== "http:" && url.protocol !== "https:") return null;
39
+ let path = url.pathname;
40
+ while (path.endsWith("/")) path = path.slice(0, -1);
41
+ return url.origin + path + url.search;
42
+ }
43
+
44
+ /** The discovery URL for a canonical endpoint (SPEC 5.2). */
45
+ export function discoveryUrl(endpoint: string): string {
46
+ return endpoint + "/models";
47
+ }
48
+
49
+ export interface CandidateModel {
50
+ api?: string;
51
+ baseUrl?: string;
52
+ id?: string;
53
+ }
54
+
55
+ /**
56
+ * Discovery candidate rule (SPEC 5.1): the selected configured
57
+ * `openai-completions` model with a valid HTTP(S) base URL, regardless of
58
+ * provider name, hostname, port, or launch method.
59
+ */
60
+ export function isDiscoveryCandidate(model: CandidateModel): boolean {
61
+ if (model.api !== "openai-completions") return false;
62
+ return normalizeEndpoint(model.baseUrl ?? "") !== null;
63
+ }
64
+
65
+ /**
66
+ * Positive identification (SPEC 5.2): successful JSON with an OpenAI-style
67
+ * `data` array containing an object whose `id` exactly matches the requested
68
+ * model and whose `owned_by` is exactly `"splash"`.
69
+ */
70
+ export function validateIdentityResponse(body: unknown, modelId: string): boolean {
71
+ if (!isPlainObject(body)) return false;
72
+ if (!Array.isArray(body.data)) return false;
73
+ return body.data.some((entry) => {
74
+ if (!isPlainObject(entry)) return false;
75
+ return entry.id === modelId && entry.owned_by === "splash";
76
+ });
77
+ }