@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.
@@ -0,0 +1,45 @@
1
+ /**
2
+ * Request eligibility, payload enrichment, and stream attribution
3
+ * (SPECIFICATION.md sections 6 and 9).
4
+ *
5
+ * Enrichment is non-mutating: eligible payloads are replaced, never edited
6
+ * in place. Anything malformed, non-streaming, or unmatched passes through
7
+ * unchanged (null result).
8
+ */
9
+
10
+ import type { RequestState } from "./progress.ts";
11
+
12
+ export function isPlainObject(value: unknown): value is Record<string, unknown> {
13
+ if (typeof value !== "object" || value === null) return false;
14
+ const proto = Object.getPrototypeOf(value);
15
+ return proto === Object.prototype || proto === null;
16
+ }
17
+
18
+ /**
19
+ * Section 6: for a verified, owned, streaming JSON chat-completions request
20
+ * to the exact model, return a replacement payload with
21
+ * `return_progress: true` and `stream_options.include_usage: true`
22
+ * (preserving other `stream_options`). Returns null when the payload must
23
+ * pass through unchanged.
24
+ */
25
+ export function enrichPayload(payload: unknown, modelId: string): Record<string, unknown> | null {
26
+ if (!isPlainObject(payload)) return null;
27
+ if (payload.stream !== true) return null;
28
+ if (typeof payload.model !== "string" || payload.model !== modelId) return null;
29
+ const streamOptions: Record<string, unknown> = isPlainObject(payload.stream_options)
30
+ ? { ...payload.stream_options }
31
+ : {};
32
+ streamOptions.include_usage = true;
33
+ return { ...payload, return_progress: true, stream_options: streamOptions };
34
+ }
35
+
36
+ /**
37
+ * Stream attribution (SPEC 9): a raw stream event feeds an owned request
38
+ * only when provider, api, and model all match.
39
+ */
40
+ export function matchesStreamRequest(
41
+ request: RequestState,
42
+ event: { provider: string; api: string; model: string },
43
+ ): boolean {
44
+ return request.provider === event.provider && request.api === event.api && request.modelId === event.model;
45
+ }
package/src/ui.ts ADDED
@@ -0,0 +1,173 @@
1
+ /**
2
+ * Working-message and widget ownership (SPECIFICATION.md sections 8.1, 8.3,
3
+ * 10.3).
4
+ *
5
+ * The extension only touches its namespaced widget `pi-splash-stats` and
6
+ * restores the working message only when it actually overrode it. Chat prefill
7
+ * uses the working message; compaction/branch-summary prefill uses the
8
+ * above-editor widget so Pi's own spinner (which occupies the working message)
9
+ * is left untouched. Identical lines are not re-rendered; same-phase updates
10
+ * coalesce to at most 10 per second while phase changes and cleanup render
11
+ * immediately. UI API failures disable the affected display without affecting
12
+ * inference.
13
+ */
14
+
15
+ export const WIDGET_KEY = "pi-splash-stats";
16
+ export const COALESCE_MS = 100;
17
+
18
+ export interface UiAdapter {
19
+ setWorkingMessage(message?: string): void;
20
+ setWidget(key: string, content: string[] | undefined): void;
21
+ }
22
+
23
+ interface PendingRender {
24
+ phase: "prefill" | "generation";
25
+ line: string;
26
+ /** "working" = chat prefill (working message); "widget" = summary prefill + generation. */
27
+ target: "working" | "widget";
28
+ }
29
+
30
+ export class UiController {
31
+ private readonly ui: UiAdapter;
32
+ private timer: ReturnType<typeof setTimeout> | null = null;
33
+ private pending: PendingRender | null = null;
34
+ private lastWorking: string | null = null; // chat prefill (working message)
35
+ private lastWidget: string | null = null; // summary prefill + generation (widget)
36
+ private ownsWorkingMessage = false;
37
+ private phase: "prefill" | "generation" | "none" = "none";
38
+ private workingDisabled = false;
39
+ private widgetDisabled = false;
40
+ private disposed = false;
41
+
42
+ constructor(ui: UiAdapter) {
43
+ this.ui = ui;
44
+ }
45
+
46
+ /** Show/replace the chat prefill working-message line (null clears everything). */
47
+ showPrefill(line: string | null): void {
48
+ if (this.disposed) return;
49
+ if (line === null) {
50
+ this.clearAll();
51
+ return;
52
+ }
53
+ if (this.workingDisabled || line === this.lastWorking) return;
54
+ this.phase = "prefill";
55
+ this.schedule({ phase: "prefill", line, target: "working" }, false);
56
+ }
57
+
58
+ /**
59
+ * Show/replace the summary prefill line in the above-editor widget (null
60
+ * clears everything). Used for compaction/branch phases, where Pi's own
61
+ * spinner occupies the working message and must not be touched (SPEC 8.1).
62
+ */
63
+ showPrefillWidget(line: string | null): void {
64
+ if (this.disposed) return;
65
+ if (line === null) {
66
+ this.clearAll();
67
+ return;
68
+ }
69
+ if (this.widgetDisabled || line === this.lastWidget) return;
70
+ this.phase = "prefill";
71
+ this.schedule({ phase: "prefill", line, target: "widget" }, false);
72
+ }
73
+
74
+ /**
75
+ * Show/replace the generation widget line. The prefill→generation phase
76
+ * transition renders immediately; later same-phase updates coalesce within
77
+ * the 100 ms bound (SPEC 10.3). For chat the transition also restores the
78
+ * working message; for summaries it is a no-op (we never owned it).
79
+ */
80
+ showGeneration(line: string | null): void {
81
+ if (this.disposed) return;
82
+ if (line === null) {
83
+ this.clearAll();
84
+ return;
85
+ }
86
+ if (this.widgetDisabled || line === this.lastWidget) return;
87
+ const transition = this.phase !== "generation";
88
+ if (transition) {
89
+ this.flushTimer();
90
+ this.restoreWorkingMessage();
91
+ }
92
+ this.phase = "generation";
93
+ this.schedule({ phase: "generation", line, target: "widget" }, transition);
94
+ }
95
+
96
+ /** Clear only this extension's owned UI (SPEC 8.3). */
97
+ clearAll(): void {
98
+ this.flushTimer();
99
+ this.restoreWorkingMessage();
100
+ if (this.lastWidget !== null && !this.widgetDisabled) {
101
+ try {
102
+ this.ui.setWidget(WIDGET_KEY, undefined);
103
+ } catch {
104
+ this.widgetDisabled = true;
105
+ }
106
+ }
107
+ this.lastWorking = null;
108
+ this.lastWidget = null;
109
+ this.phase = "none";
110
+ }
111
+
112
+ /** Cancel timers; no event-loop handle may survive shutdown (SPEC 10.3). */
113
+ dispose(): void {
114
+ if (this.timer !== null) {
115
+ clearTimeout(this.timer);
116
+ this.timer = null;
117
+ }
118
+ this.pending = null;
119
+ this.disposed = true;
120
+ }
121
+
122
+ private restoreWorkingMessage(): void {
123
+ if (!this.ownsWorkingMessage) return;
124
+ this.ownsWorkingMessage = false;
125
+ try {
126
+ this.ui.setWorkingMessage(undefined);
127
+ } catch {
128
+ // Working-message restore failed; do not retry against a broken UI.
129
+ }
130
+ }
131
+
132
+ private schedule(render: PendingRender, immediate: boolean): void {
133
+ if (this.timer !== null) {
134
+ // Coalesce: at most one pending same-phase render within 100ms.
135
+ this.pending = render;
136
+ return;
137
+ }
138
+ this.pending = render;
139
+ if (immediate) {
140
+ this.flushTimer();
141
+ } else {
142
+ this.timer = setTimeout(() => this.flushTimer(), COALESCE_MS);
143
+ }
144
+ }
145
+
146
+ private flushTimer(): void {
147
+ if (this.timer !== null) {
148
+ clearTimeout(this.timer);
149
+ this.timer = null;
150
+ }
151
+ const render = this.pending;
152
+ this.pending = null;
153
+ if (!render) return;
154
+ if (render.target === "working") {
155
+ if (render.line === this.lastWorking) return;
156
+ try {
157
+ this.ui.setWorkingMessage(render.line);
158
+ this.ownsWorkingMessage = true;
159
+ this.lastWorking = render.line;
160
+ } catch {
161
+ this.workingDisabled = true;
162
+ }
163
+ } else {
164
+ if (render.line === this.lastWidget) return;
165
+ try {
166
+ this.ui.setWidget(WIDGET_KEY, [render.line]);
167
+ this.lastWidget = render.line;
168
+ } catch {
169
+ this.widgetDisabled = true;
170
+ }
171
+ }
172
+ }
173
+ }