@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.
- package/CHANGELOG.md +55 -0
- package/LICENSE +190 -0
- package/README.md +194 -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/CHANGELOG.md
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
Notable changes to this project. Entries are grouped by release; the latest is listed first.
|
|
4
|
+
This repository follows [Keep a Changelog](https://keepachangelog.com/) for entry style.
|
|
5
|
+
|
|
6
|
+
## [0.1.0]
|
|
7
|
+
|
|
8
|
+
Initial release of the `pi-splash-stats` Pi extension.
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- **Cache-aware prefill progress.** A 20-cell progress bar with percentage, elapsed time, and
|
|
13
|
+
uncached throughput (`Prefilling... ████░░ NN% · 2s · 20.0 tok/s`) while a verified Splash request
|
|
14
|
+
is being processed. Cached tokens are not re-counted.
|
|
15
|
+
- **Live generation count.** An approximate token count that grows while the answer streams
|
|
16
|
+
(`Generating... ≈123 tok`), marked with `≈` because it is an estimate.
|
|
17
|
+
- **Identity-verified Splash detection.** The extension verifies a provider through the bounded,
|
|
18
|
+
deduplicated, cached Splash discovery protocol (2s deadline; 60s success / 5s failure cache) and
|
|
19
|
+
only enriches and observes requests to a verified Splash backend. Any other provider passes through
|
|
20
|
+
unchanged.
|
|
21
|
+
- **Two transports.** Chat is observed through Pi's provider request/stream hooks; compaction and
|
|
22
|
+
branch summaries are observed through a scoped global `fetch` observer, because those requests do
|
|
23
|
+
not fire the provider hooks (see ADR 0002).
|
|
24
|
+
- **TUI-only rendering.** Statistics appear only in the interactive terminal UI. RPC, print, and JSON
|
|
25
|
+
modes produce no statistics messages, terminal output, notifications, transcript entries, or
|
|
26
|
+
protocol additions.
|
|
27
|
+
- **Bounded, coalesced updates.** Display updates are coalesced to at most 10 per second; phase
|
|
28
|
+
changes and cleanup render immediately.
|
|
29
|
+
- **Request ownership.** Per-request generation and model-selection tracking rejects late,
|
|
30
|
+
out-of-order, or stale chunks so concurrent streams cannot mix counts; an armed-request guard
|
|
31
|
+
prevents a stale boundary event from clearing a newer active request.
|
|
32
|
+
- **Graceful failure.** A throwing UI API disables the affected display without failing the request;
|
|
33
|
+
an abrupt stream clears the display without an unhandled rejection; a failed discovery leaves the
|
|
34
|
+
original request unchanged.
|
|
35
|
+
- **Lifecycle handling.** A fresh discovery cache on `session_start`, disposal on `session_shutdown`,
|
|
36
|
+
and a `runtimeGeneration` bump on each new runtime.
|
|
37
|
+
- **Tests and verification.** Offline `node:test` unit and wiring suites, a package-content allowlist
|
|
38
|
+
check, and real-Pi end-to-end checks (checkout RPC, headless JSON, packed archive). A separate
|
|
39
|
+
real-Pi verification harness drives the terminal UI and non-TUI modes end to end, including a
|
|
40
|
+
packed-package journey that installs the `npm pack` artifact through the Pi manifest.
|
|
41
|
+
- **Documentation.** Architecture, testing, troubleshooting (with a security section), ADRs
|
|
42
|
+
(thin extension and layered tests; transport coverage), and release guidance.
|
|
43
|
+
|
|
44
|
+
### Packaging
|
|
45
|
+
|
|
46
|
+
- Ships `package.json`, `README.md`, `LICENSE`, `CHANGELOG.md`, and non-hidden `src/**/*.ts` files,
|
|
47
|
+
excluding `*.test.ts`, `*.spec.ts`, and `AGENTS.md`/`CLAUDE.md`/`GEMINI.md`. Tests, e2e files, docs,
|
|
48
|
+
agent instructions, and secrets are not packed.
|
|
49
|
+
- The packed e2e path lists the tarball with portable `tar -tf` (GNU- and BSD-tar compatible).
|
|
50
|
+
|
|
51
|
+
### Publishing
|
|
52
|
+
|
|
53
|
+
- Disabled by default with `"private": true` and the `ENABLE_NPM_PUBLISH` repository-variable gate.
|
|
54
|
+
Releases require a reviewed version/changelog pull request and a manually authorized stable
|
|
55
|
+
`vX.Y.Z` tag; there is no automatic tag on merge.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to the Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
Copyright 2025 Headroom Contributors
|
|
179
|
+
|
|
180
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
181
|
+
you may not use this file except in compliance with the License.
|
|
182
|
+
You may obtain a copy of the License at
|
|
183
|
+
|
|
184
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
185
|
+
|
|
186
|
+
Unless required by applicable law or agreed to in writing, software
|
|
187
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
188
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
189
|
+
See the License for the specific language governing permissions and
|
|
190
|
+
limitations under the License.
|
package/README.md
CHANGED
|
@@ -1,3 +1,195 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Pi Splash Stats
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A Pi extension that shows live inference statistics for OpenAI-compatible **Splash** servers in the
|
|
4
|
+
interactive terminal UI: a **cache-aware prefill progress bar** while the prompt is being processed,
|
|
5
|
+
and a **live generation token count** while the model streams its answer.
|
|
6
|
+
|
|
7
|
+
It is a passive observer. It enriches and watches the inference traffic Pi already sends to a
|
|
8
|
+
verified Splash backend, then renders two transient status lines in the TUI. It changes no prompts,
|
|
9
|
+
no tools, and no responses, and it stays completely silent in every non-interactive mode.
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
── ⠸ Prefilling... ██████████░░░░░░░░░░ 50% · 2s · 20.0 tok/s ─────────────────────
|
|
13
|
+
Generating... ≈5 tok
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## What you get
|
|
17
|
+
|
|
18
|
+
- **Cache-aware prefill progress.** A 20-cell bar with percentage, elapsed time, and uncached
|
|
19
|
+
throughput (`Prefilling... ████░░░░ NN% · 2s · 20.0 tok/s`). Cached tokens are not re-counted, so
|
|
20
|
+
the bar reflects the work actually being done.
|
|
21
|
+
- **Live generation count.** An approximate token count that grows while the answer streams
|
|
22
|
+
(`Generating... ≈123 tok`), marked with `≈` because it is an estimate, not a final total.
|
|
23
|
+
- **TUI only.** The statistics appear only in the interactive terminal UI. RPC, print, and JSON
|
|
24
|
+
modes produce no statistics messages, no terminal output, no notifications, and no transcript
|
|
25
|
+
entries (SPECIFICATION.md §8.4, AC-13).
|
|
26
|
+
- **Identity-verified.** It only observes and enriches requests to a Splash backend it has verified
|
|
27
|
+
through the Splash discovery protocol. Requests to any other provider pass through untouched.
|
|
28
|
+
- **Bounded and safe.** Updates are coalesced to at most 10 per second (phase changes and cleanup
|
|
29
|
+
render immediately). If the UI API throws, the display is disabled without failing the request.
|
|
30
|
+
If a stream is cut off abruptly, the display is cleared without an unhandled rejection. If
|
|
31
|
+
discovery fails, the original request is sent unchanged.
|
|
32
|
+
|
|
33
|
+
## Requirements and compatibility
|
|
34
|
+
|
|
35
|
+
| Requirement | Detail |
|
|
36
|
+
| --- | --- |
|
|
37
|
+
| Node.js | 22.18 or newer. CI runs Node 22 and 24 on Linux with the same commands; local verification here uses Node 22. |
|
|
38
|
+
| Pi | 1.5.2 baseline for the e2e checks, pinned in `scripts/quality.json`. |
|
|
39
|
+
| Platform | Linux is tested in CI. Other operating systems are not currently verified. |
|
|
40
|
+
| Dependencies | None. `npm install` is not required. E2E additionally needs a Pi binary and a system `tar`. |
|
|
41
|
+
| Network | `npm test` and `npm run check` are offline. At runtime the extension makes a single bounded, cached discovery request to the Splash backend to verify provider identity; it makes no other network calls. |
|
|
42
|
+
|
|
43
|
+
Nothing is built. Pi loads the TypeScript directly, and the tests rely on Node's TypeScript
|
|
44
|
+
stripping. There is no lint, typecheck, or build step; stripping does not typecheck.
|
|
45
|
+
|
|
46
|
+
## Install
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
# From a local checkout
|
|
50
|
+
pi install /absolute/path/to/pi-splash-stats
|
|
51
|
+
|
|
52
|
+
# From Git
|
|
53
|
+
pi install git:github.com/cltec/pi-splash-stats
|
|
54
|
+
|
|
55
|
+
# From npm (only after publishing is explicitly enabled)
|
|
56
|
+
pi install npm:@cltec/pi-splash-stats
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
For one run without changing Pi settings, use `pi -e /path/to/pi-splash-stats`.
|
|
60
|
+
|
|
61
|
+
The package is currently `private` and not published to npm; the `npm:` form works only after
|
|
62
|
+
publishing is explicitly enabled (see [docs/RELEASING.md](docs/RELEASING.md)).
|
|
63
|
+
|
|
64
|
+
## Usage
|
|
65
|
+
|
|
66
|
+
Install the extension and use Pi as usual. The statistics appear automatically while a chat to a
|
|
67
|
+
**verified Splash backend** is in flight — no configuration, flags, commands, or launcher handshake.
|
|
68
|
+
Activation depends only on the backend serving the current request, never on how Pi was launched
|
|
69
|
+
(SPECIFICATION.md §2, Decision D1, AC-02/AC-15). The statistics are transient: they clear when the
|
|
70
|
+
response completes or is aborted.
|
|
71
|
+
|
|
72
|
+
Two launch workflows both work and produce equivalent statistics for the same Splash-served model:
|
|
73
|
+
|
|
74
|
+
- **`splash pi ...`** — the Splash launcher starts Pi already pointed at a running Splash model. The
|
|
75
|
+
extension observes that model's requests exactly as it would for a directly launched Pi; it does not
|
|
76
|
+
inspect the launcher, parent process, or a particular provider name. If you switch to a non-Splash
|
|
77
|
+
(e.g. cloud) model, the stats clear immediately and subsequent requests are left untouched.
|
|
78
|
+
- **Pi launched directly** — configure Pi with a Splash-served OpenAI-compatible model (including a
|
|
79
|
+
server on a non-default port) and run Pi normally. The extension verifies the backend through the
|
|
80
|
+
Splash discovery protocol and shows stats while that model streams. Arbitrary configured provider
|
|
81
|
+
names do not prevent activation; a non-Splash provider simply shows no stats.
|
|
82
|
+
|
|
83
|
+
The extension reads no configuration, environment variables, or files, keeps no state between
|
|
84
|
+
invocations, and starts no background work.
|
|
85
|
+
|
|
86
|
+
## Remove
|
|
87
|
+
|
|
88
|
+
Use `pi remove` with the same source string you installed from. Pi matches sources exactly, so
|
|
89
|
+
`/absolute/path`, `git:...`, and `npm:...` forms are distinct:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
pi remove /absolute/path/to/pi-splash-stats
|
|
93
|
+
pi remove git:github.com/cltec/pi-splash-stats
|
|
94
|
+
pi remove npm:@cltec/pi-splash-stats
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
The extension keeps no configuration or state of its own. If you loaded it with `pi -e`, there is
|
|
98
|
+
nothing to remove.
|
|
99
|
+
|
|
100
|
+
## Development commands
|
|
101
|
+
|
|
102
|
+
| Task | Command | Notes |
|
|
103
|
+
| --- | --- | --- |
|
|
104
|
+
| Unit, wiring, and tooling tests | `npm test` | Offline; no Pi process, no `npm pack`, no network. |
|
|
105
|
+
| Package check | `npm run check:package` | Asserts the `npm pack` contents. |
|
|
106
|
+
| Full local check | `npm run check` | `npm test && npm run check:package`. |
|
|
107
|
+
| End-to-end | `npm run test:e2e` | Real Pi: checkout RPC, headless JSON, packed archive. |
|
|
108
|
+
| One test file | `node --test test/extension.test.ts` | Replace with the file you are changing. |
|
|
109
|
+
|
|
110
|
+
`npm run check` does not run e2e. Run e2e when changing extension wiring, the command contract,
|
|
111
|
+
package contents, or the Pi baseline. No dependency installation is needed for any command, but
|
|
112
|
+
e2e needs a compatible Pi binary.
|
|
113
|
+
|
|
114
|
+
The e2e runner creates a temporary home, config directory, and working directory and passes only an
|
|
115
|
+
allowlisted environment. It runs Pi offline, makes no provider calls, bounds shutdown, cleans up,
|
|
116
|
+
and writes a sanitized schema-1 result instead of raw logs.
|
|
117
|
+
|
|
118
|
+
- **Checkout:** Pi loads `src/index.ts` with `-e`.
|
|
119
|
+
- **Headless JSON:** Pi runs `--mode json` and the test asserts the extension emits no custom
|
|
120
|
+
messages and exits cleanly.
|
|
121
|
+
- **Packed archive:** the runner packs the current tree, or reuses an exact checked archive via
|
|
122
|
+
`PACKAGE_ARCHIVE=/absolute/file.tgz`. It lists and extracts the tarball with a system `tar`, then
|
|
123
|
+
loads the extracted directory through a temporary Pi `settings.json` `packages` entry and discovers
|
|
124
|
+
the extension from the manifest. It does not run `pi install` or contact a registry; that install
|
|
125
|
+
path is a known coverage limit.
|
|
126
|
+
|
|
127
|
+
Set `E2E_RESULT_PATH` to change the result file. `scripts/summarize-e2e.mjs` renders only known
|
|
128
|
+
fields from it. See [docs/TESTING.md](docs/TESTING.md).
|
|
129
|
+
|
|
130
|
+
A separate real-Pi verification harness drives the terminal UI and non-TUI modes end to end,
|
|
131
|
+
including a **packed-package** journey that installs the `npm pack` artifact through the manifest.
|
|
132
|
+
See [`.cursor/skills/verify-pi-splash-stats/SKILL.md`](.cursor/skills/verify-pi-splash-stats/SKILL.md).
|
|
133
|
+
|
|
134
|
+
## Packaging
|
|
135
|
+
|
|
136
|
+
`npm run check:package` treats packaging as an allowlist, not a denylist. The package ships
|
|
137
|
+
`package.json`, `README.md`, `LICENSE`, `CHANGELOG.md`, and non-hidden `src/**/*.ts` files, excluding
|
|
138
|
+
`*.test.ts`, `*.spec.ts`, and `AGENTS.md`/`CLAUDE.md`/`GEMINI.md`. Agent instructions, tests, e2e
|
|
139
|
+
files, docs, environment files, credentials, and tarballs must not be packed. When you add a resource
|
|
140
|
+
directory that users need, add it to the `files` allowlist and update the check deliberately.
|
|
141
|
+
|
|
142
|
+
## Releases
|
|
143
|
+
|
|
144
|
+
This package is not a publishing project. It ships with `"private": true`, and the release workflow
|
|
145
|
+
additionally requires the `ENABLE_NPM_PUBLISH` repository variable. Releases are manual and
|
|
146
|
+
explicitly authorized: a reviewed pull request changes the version and `CHANGELOG.md`, then a
|
|
147
|
+
maintainer creates a canonical stable `vX.Y.Z` tag. There is no automatic tag on merge. Concrete,
|
|
148
|
+
non-placeholder repository metadata is required; `private` must also be set to `false` intentionally
|
|
149
|
+
before publishing.
|
|
150
|
+
|
|
151
|
+
When enabled, the workflow runs source smoke, packs the final `release/package.tgz`, re-runs e2e with
|
|
152
|
+
`PACKAGE_ARCHIVE` pointed at that archive, uploads the checked artifact, and publishes those same
|
|
153
|
+
bytes. E2E and offline steps may create temporary packs; only the final release tarball is preserved
|
|
154
|
+
and published. Setup, OIDC trusted publishing, and the maintainer procedure live in
|
|
155
|
+
[docs/RELEASING.md](docs/RELEASING.md).
|
|
156
|
+
|
|
157
|
+
## Troubleshooting
|
|
158
|
+
|
|
159
|
+
Common local, e2e, packaging, and release-gate symptoms are listed in
|
|
160
|
+
[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md). Start with the failing command's own output and
|
|
161
|
+
the sanitized e2e artifact; do not paste credentials, prompts, or real home-directory paths into an
|
|
162
|
+
issue.
|
|
163
|
+
|
|
164
|
+
## Support
|
|
165
|
+
|
|
166
|
+
- Open an issue at https://github.com/cltec/pi-splash-stats/issues for reproducible bugs and
|
|
167
|
+
documentation gaps.
|
|
168
|
+
- Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md), not in a public issue.
|
|
169
|
+
|
|
170
|
+
## Documentation
|
|
171
|
+
|
|
172
|
+
| Document | Contents |
|
|
173
|
+
| --- | --- |
|
|
174
|
+
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Modules, request flow, transports, modes, and failure behavior. |
|
|
175
|
+
| [docs/TESTING.md](docs/TESTING.md) | Test layers, e2e isolation, the real-Pi verification harness, and what is not covered. |
|
|
176
|
+
| [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Common local, e2e, packaging, and release-gate symptoms. |
|
|
177
|
+
| [docs/adr/0001-thin-extension-and-layered-tests.md](docs/adr/0001-thin-extension-and-layered-tests.md) | Why the adapter is thin and the tests are layered. |
|
|
178
|
+
| [docs/adr/0002-transport-coverage.md](docs/adr/0002-transport-coverage.md) | Why summaries use a scoped fetch observer. |
|
|
179
|
+
| [docs/RELEASING.md](docs/RELEASING.md) | Release setup and maintainer procedure. |
|
|
180
|
+
| [CONTRIBUTING.md](CONTRIBUTING.md) | Workflow, standards, and pull request checklist. |
|
|
181
|
+
| [AGENTS.md](AGENTS.md) | Agent instructions: verified commands, invariants, boundaries. |
|
|
182
|
+
| [SECURITY.md](SECURITY.md) | Reporting and security scope. |
|
|
183
|
+
| [CHANGELOG.md](CHANGELOG.md) | Notable changes. |
|
|
184
|
+
|
|
185
|
+
## Security
|
|
186
|
+
|
|
187
|
+
The extension runs no external commands and reads no configuration. At runtime it makes a single
|
|
188
|
+
bounded, cached discovery request to the Splash backend and otherwise only observes the inference
|
|
189
|
+
traffic Pi already sends. Extensions run inside the Pi process with the same operating-system
|
|
190
|
+
permissions as Pi, so review any extension before installing it. Report vulnerabilities privately;
|
|
191
|
+
see [SECURITY.md](SECURITY.md).
|
|
192
|
+
|
|
193
|
+
## License
|
|
194
|
+
|
|
195
|
+
Apache-2.0. See [LICENSE](LICENSE).
|
package/package.json
CHANGED
|
@@ -1,6 +1,33 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cltec/pi-splash-stats",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"description": "
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"private": false,
|
|
5
|
+
"description": "Pi extension that displays live inference statistics for OpenAI-compatible Splash servers.",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"main": "./src/index.ts",
|
|
8
|
+
"keywords": ["pi-package", "pi", "extension"],
|
|
9
|
+
"pi": { "extensions": ["./src/index.ts"] },
|
|
10
|
+
"files": [
|
|
11
|
+
"src",
|
|
12
|
+
"!src/**/AGENTS.md",
|
|
13
|
+
"!src/**/CLAUDE.md",
|
|
14
|
+
"!src/**/GEMINI.md",
|
|
15
|
+
"!src/**/.env*",
|
|
16
|
+
"!src/**/*.env",
|
|
17
|
+
"README.md",
|
|
18
|
+
"LICENSE",
|
|
19
|
+
"CHANGELOG.md"
|
|
20
|
+
],
|
|
21
|
+
"scripts": {
|
|
22
|
+
"test": "node --test \"test/**/*.test.ts\"",
|
|
23
|
+
"check:package": "node scripts/check-package.mjs",
|
|
24
|
+
"check": "npm test && npm run check:package",
|
|
25
|
+
"test:e2e": "node e2e/smoke.ts"
|
|
26
|
+
},
|
|
27
|
+
"peerDependencies": { "@earendil-works/pi-coding-agent": "*" },
|
|
28
|
+
"engines": { "node": ">=22.18.0" },
|
|
29
|
+
"license": "Apache-2.0",
|
|
30
|
+
"repository": { "type": "git", "url": "git+https://github.com/cltec/pi-splash-stats.git" },
|
|
31
|
+
"bugs": { "url": "https://github.com/cltec/pi-splash-stats/issues" },
|
|
32
|
+
"homepage": "https://github.com/cltec/pi-splash-stats#readme"
|
|
33
|
+
}
|
package/src/discovery.ts
ADDED
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Bounded authenticated discovery (SPECIFICATION.md section 5.3).
|
|
3
|
+
*
|
|
4
|
+
* Total 2s deadline per attempt, in-flight dedupe per endpoint + auth
|
|
5
|
+
* context, 60s positive / 5s negative cache, no redirects, 1 MiB response
|
|
6
|
+
* bound, cancellation on dispose. Cache keys never contain secrets.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
import {
|
|
10
|
+
discoveryUrl,
|
|
11
|
+
isDiscoveryCandidate,
|
|
12
|
+
MAX_RESPONSE_BYTES,
|
|
13
|
+
normalizeEndpoint,
|
|
14
|
+
validateIdentityResponse,
|
|
15
|
+
type CandidateModel,
|
|
16
|
+
} from "./identity.ts";
|
|
17
|
+
|
|
18
|
+
export interface AuthContext {
|
|
19
|
+
apiKey?: string;
|
|
20
|
+
headers?: Record<string, string>;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/** Minimal response surface so tests can inject fakes. */
|
|
24
|
+
export interface DiscoveryResponse {
|
|
25
|
+
ok: boolean;
|
|
26
|
+
status: number;
|
|
27
|
+
headers?: { get(name: string): string | null };
|
|
28
|
+
arrayBuffer(): Promise<ArrayBuffer>;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export type DiscoveryFetch = (
|
|
32
|
+
url: string,
|
|
33
|
+
init?: { method?: string; redirect?: string; signal?: AbortSignal; headers?: Record<string, string> },
|
|
34
|
+
) => Promise<DiscoveryResponse>;
|
|
35
|
+
|
|
36
|
+
export interface DiscoveryOptions {
|
|
37
|
+
fetchImpl?: DiscoveryFetch;
|
|
38
|
+
now?: () => number;
|
|
39
|
+
deadlineMs?: number;
|
|
40
|
+
positiveTtlMs?: number;
|
|
41
|
+
negativeTtlMs?: number;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
interface CacheEntry {
|
|
45
|
+
verified: boolean;
|
|
46
|
+
expiresAt: number;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Non-secret identity of an auth context (SPEC 5.3): key presence plus
|
|
51
|
+
* sorted header names. Never stores raw secrets.
|
|
52
|
+
*/
|
|
53
|
+
export function authContextId(auth: AuthContext): string {
|
|
54
|
+
const names = Object.keys(auth.headers ?? {}).sort().join(",");
|
|
55
|
+
return (auth.apiKey ? "key" : "none") + ":" + names;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
export class DiscoveryCache {
|
|
59
|
+
private readonly fetchImpl: DiscoveryFetch;
|
|
60
|
+
private readonly now: () => number;
|
|
61
|
+
private readonly deadlineMs: number;
|
|
62
|
+
private readonly positiveTtlMs: number;
|
|
63
|
+
private readonly negativeTtlMs: number;
|
|
64
|
+
private readonly entries = new Map<string, CacheEntry>();
|
|
65
|
+
private readonly inFlight = new Map<string, Promise<boolean>>();
|
|
66
|
+
private readonly pending = new Set<AbortController>();
|
|
67
|
+
private disposed = false;
|
|
68
|
+
|
|
69
|
+
constructor(options: DiscoveryOptions = {}) {
|
|
70
|
+
this.fetchImpl = options.fetchImpl ?? ((url, init) => fetch(url, init));
|
|
71
|
+
this.now = options.now ?? Date.now;
|
|
72
|
+
this.deadlineMs = options.deadlineMs ?? 2000;
|
|
73
|
+
this.positiveTtlMs = options.positiveTtlMs ?? 60_000;
|
|
74
|
+
this.negativeTtlMs = options.negativeTtlMs ?? 5_000;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* Verify that `model`'s endpoint serves the model as Splash-owned.
|
|
79
|
+
* Resolves `true` only on a fresh or newly verified identity. Bounded by
|
|
80
|
+
* the per-attempt deadline; cached and in-flight results are reused.
|
|
81
|
+
*/
|
|
82
|
+
async ensure(model: CandidateModel, resolveAuth: () => Promise<AuthContext>): Promise<boolean> {
|
|
83
|
+
if (this.disposed) return false;
|
|
84
|
+
if (!isDiscoveryCandidate(model) || typeof model.id !== "string" || model.id === "") return false;
|
|
85
|
+
const endpoint = normalizeEndpoint(model.baseUrl ?? "");
|
|
86
|
+
if (!endpoint) return false;
|
|
87
|
+
|
|
88
|
+
const started = this.now();
|
|
89
|
+
let auth: AuthContext;
|
|
90
|
+
try {
|
|
91
|
+
auth = await resolveAuth();
|
|
92
|
+
} catch {
|
|
93
|
+
auth = { apiKey: undefined, headers: undefined };
|
|
94
|
+
}
|
|
95
|
+
if (this.disposed) return false;
|
|
96
|
+
|
|
97
|
+
const key = endpoint + "|" + authContextId(auth);
|
|
98
|
+
const entry = this.entries.get(key);
|
|
99
|
+
if (entry && entry.expiresAt > this.now()) return entry.verified;
|
|
100
|
+
const existing = this.inFlight.get(key);
|
|
101
|
+
if (existing) return existing;
|
|
102
|
+
|
|
103
|
+
const remaining = this.deadlineMs - (this.now() - started);
|
|
104
|
+
const attempt =
|
|
105
|
+
remaining <= 0
|
|
106
|
+
? Promise.resolve(false)
|
|
107
|
+
: this.attempt(endpoint, model.id, auth, remaining);
|
|
108
|
+
this.inFlight.set(key, attempt);
|
|
109
|
+
try {
|
|
110
|
+
const verified = await attempt;
|
|
111
|
+
if (!this.disposed) {
|
|
112
|
+
this.entries.set(key, {
|
|
113
|
+
verified,
|
|
114
|
+
expiresAt: this.now() + (verified ? this.positiveTtlMs : this.negativeTtlMs),
|
|
115
|
+
});
|
|
116
|
+
}
|
|
117
|
+
return verified;
|
|
118
|
+
} finally {
|
|
119
|
+
this.inFlight.delete(key);
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
private async attempt(
|
|
124
|
+
endpoint: string,
|
|
125
|
+
modelId: string,
|
|
126
|
+
auth: AuthContext,
|
|
127
|
+
budgetMs: number,
|
|
128
|
+
): Promise<boolean> {
|
|
129
|
+
const controller = new AbortController();
|
|
130
|
+
this.pending.add(controller);
|
|
131
|
+
const timer = setTimeout(() => controller.abort(), budgetMs);
|
|
132
|
+
try {
|
|
133
|
+
const headers: Record<string, string> = { ...(auth.headers ?? {}) };
|
|
134
|
+
if (auth.apiKey) headers["Authorization"] = `Bearer ${auth.apiKey}`;
|
|
135
|
+
const response = await this.fetchImpl(discoveryUrl(endpoint), {
|
|
136
|
+
method: "GET",
|
|
137
|
+
redirect: "manual",
|
|
138
|
+
signal: controller.signal,
|
|
139
|
+
headers,
|
|
140
|
+
});
|
|
141
|
+
if (response.status >= 300 && response.status < 400) return false;
|
|
142
|
+
if (!response.ok) return false;
|
|
143
|
+
const declared = Number(response.headers?.get("content-length") ?? "");
|
|
144
|
+
if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) return false;
|
|
145
|
+
const buffer = await response.arrayBuffer();
|
|
146
|
+
if (buffer.byteLength > MAX_RESPONSE_BYTES) return false;
|
|
147
|
+
let body: unknown;
|
|
148
|
+
try {
|
|
149
|
+
body = JSON.parse(new TextDecoder().decode(buffer));
|
|
150
|
+
} catch {
|
|
151
|
+
return false;
|
|
152
|
+
}
|
|
153
|
+
return validateIdentityResponse(body, modelId);
|
|
154
|
+
} catch {
|
|
155
|
+
return false;
|
|
156
|
+
} finally {
|
|
157
|
+
clearTimeout(timer);
|
|
158
|
+
this.pending.delete(controller);
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/** Cancel in-flight probes and stop all further caching (SPEC 9). */
|
|
163
|
+
dispose(): void {
|
|
164
|
+
this.disposed = true;
|
|
165
|
+
for (const controller of this.pending) controller.abort();
|
|
166
|
+
this.pending.clear();
|
|
167
|
+
this.inFlight.clear();
|
|
168
|
+
this.entries.clear();
|
|
169
|
+
}
|
|
170
|
+
}
|