@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 ADDED
@@ -0,0 +1,62 @@
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.1]
7
+
8
+ ### Changed
9
+
10
+ - README: credit `pi-llama-cpp-stats` as the inspiration for this extension.
11
+ - README: link the [Splash](https://github.com/incoai/splash) server repository where Splash is mentioned.
12
+
13
+ ## [0.1.0]
14
+
15
+ Initial release of the `pi-splash-stats` Pi extension.
16
+
17
+ ### Added
18
+
19
+ - **Cache-aware prefill progress.** A 20-cell progress bar with percentage, elapsed time, and
20
+ uncached throughput (`Prefilling... ████░░ NN% · 2s · 20.0 tok/s`) while a verified Splash request
21
+ is being processed. Cached tokens are not re-counted.
22
+ - **Live generation count.** An approximate token count that grows while the answer streams
23
+ (`Generating... ≈123 tok`), marked with `≈` because it is an estimate.
24
+ - **Identity-verified Splash detection.** The extension verifies a provider through the bounded,
25
+ deduplicated, cached Splash discovery protocol (2s deadline; 60s success / 5s failure cache) and
26
+ only enriches and observes requests to a verified Splash backend. Any other provider passes through
27
+ unchanged.
28
+ - **Two transports.** Chat is observed through Pi's provider request/stream hooks; compaction and
29
+ branch summaries are observed through a scoped global `fetch` observer, because those requests do
30
+ not fire the provider hooks (see ADR 0002).
31
+ - **TUI-only rendering.** Statistics appear only in the interactive terminal UI. RPC, print, and JSON
32
+ modes produce no statistics messages, terminal output, notifications, transcript entries, or
33
+ protocol additions.
34
+ - **Bounded, coalesced updates.** Display updates are coalesced to at most 10 per second; phase
35
+ changes and cleanup render immediately.
36
+ - **Request ownership.** Per-request generation and model-selection tracking rejects late,
37
+ out-of-order, or stale chunks so concurrent streams cannot mix counts; an armed-request guard
38
+ prevents a stale boundary event from clearing a newer active request.
39
+ - **Graceful failure.** A throwing UI API disables the affected display without failing the request;
40
+ an abrupt stream clears the display without an unhandled rejection; a failed discovery leaves the
41
+ original request unchanged.
42
+ - **Lifecycle handling.** A fresh discovery cache on `session_start`, disposal on `session_shutdown`,
43
+ and a `runtimeGeneration` bump on each new runtime.
44
+ - **Tests and verification.** Offline `node:test` unit and wiring suites, a package-content allowlist
45
+ check, and real-Pi end-to-end checks (checkout RPC, headless JSON, packed archive). A separate
46
+ real-Pi verification harness drives the terminal UI and non-TUI modes end to end, including a
47
+ packed-package journey that installs the `npm pack` artifact through the Pi manifest.
48
+ - **Documentation.** Architecture, testing, troubleshooting (with a security section), ADRs
49
+ (thin extension and layered tests; transport coverage), and release guidance.
50
+
51
+ ### Packaging
52
+
53
+ - Ships `package.json`, `README.md`, `LICENSE`, `CHANGELOG.md`, and non-hidden `src/**/*.ts` files,
54
+ excluding `*.test.ts`, `*.spec.ts`, and `AGENTS.md`/`CLAUDE.md`/`GEMINI.md`. Tests, e2e files, docs,
55
+ agent instructions, and secrets are not packed.
56
+ - The packed e2e path lists the tarball with portable `tar -tf` (GNU- and BSD-tar compatible).
57
+
58
+ ### Publishing
59
+
60
+ - Disabled by default with `"private": true` and the `ENABLE_NPM_PUBLISH` repository-variable gate.
61
+ Releases require a reviewed version/changelog pull request and a manually authorized stable
62
+ `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,197 @@
1
- # Temporary Holding Version
1
+ # Pi Splash Stats
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A Pi extension that shows live inference statistics for OpenAI-compatible [**Splash**](https://github.com/incoai/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
+ This extension is inspired by [pi-llama-cpp-stats](https://www.npmjs.com/package/pi-llama-cpp-stats).
12
+
13
+ ```
14
+ ── ⠸ Prefilling... ██████████░░░░░░░░░░ 50% · 2s · 20.0 tok/s ─────────────────────
15
+ Generating... ≈5 tok
16
+ ```
17
+
18
+ ## What you get
19
+
20
+ - **Cache-aware prefill progress.** A 20-cell bar with percentage, elapsed time, and uncached
21
+ throughput (`Prefilling... ████░░░░ NN% · 2s · 20.0 tok/s`). Cached tokens are not re-counted, so
22
+ the bar reflects the work actually being done.
23
+ - **Live generation count.** An approximate token count that grows while the answer streams
24
+ (`Generating... ≈123 tok`), marked with `≈` because it is an estimate, not a final total.
25
+ - **TUI only.** The statistics appear only in the interactive terminal UI. RPC, print, and JSON
26
+ modes produce no statistics messages, no terminal output, no notifications, and no transcript
27
+ entries (SPECIFICATION.md §8.4, AC-13).
28
+ - **Identity-verified.** It only observes and enriches requests to a Splash backend it has verified
29
+ through the Splash discovery protocol. Requests to any other provider pass through untouched.
30
+ - **Bounded and safe.** Updates are coalesced to at most 10 per second (phase changes and cleanup
31
+ render immediately). If the UI API throws, the display is disabled without failing the request.
32
+ If a stream is cut off abruptly, the display is cleared without an unhandled rejection. If
33
+ discovery fails, the original request is sent unchanged.
34
+
35
+ ## Requirements and compatibility
36
+
37
+ | Requirement | Detail |
38
+ | --- | --- |
39
+ | Node.js | 22.18 or newer. CI runs Node 22 and 24 on Linux with the same commands; local verification here uses Node 22. |
40
+ | Pi | 1.5.2 baseline for the e2e checks, pinned in `scripts/quality.json`. |
41
+ | Platform | Linux is tested in CI. Other operating systems are not currently verified. |
42
+ | Dependencies | None. `npm install` is not required. E2E additionally needs a Pi binary and a system `tar`. |
43
+ | 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. |
44
+
45
+ Nothing is built. Pi loads the TypeScript directly, and the tests rely on Node's TypeScript
46
+ stripping. There is no lint, typecheck, or build step; stripping does not typecheck.
47
+
48
+ ## Install
49
+
50
+ ```bash
51
+ # From a local checkout
52
+ pi install /absolute/path/to/pi-splash-stats
53
+
54
+ # From Git
55
+ pi install git:github.com/cltec/pi-splash-stats
56
+
57
+ # From npm (only after publishing is explicitly enabled)
58
+ pi install npm:@cltec/pi-splash-stats
59
+ ```
60
+
61
+ For one run without changing Pi settings, use `pi -e /path/to/pi-splash-stats`.
62
+
63
+ The package is currently `private` and not published to npm; the `npm:` form works only after
64
+ publishing is explicitly enabled (see [docs/RELEASING.md](docs/RELEASING.md)).
65
+
66
+ ## Usage
67
+
68
+ Install the extension and use Pi as usual. The statistics appear automatically while a chat to a
69
+ **verified Splash backend** is in flight — no configuration, flags, commands, or launcher handshake.
70
+ Activation depends only on the backend serving the current request, never on how Pi was launched
71
+ (SPECIFICATION.md §2, Decision D1, AC-02/AC-15). The statistics are transient: they clear when the
72
+ response completes or is aborted.
73
+
74
+ Two launch workflows both work and produce equivalent statistics for the same Splash-served model:
75
+
76
+ - **`splash pi ...`** — the [Splash](https://github.com/incoai/splash) launcher starts Pi already pointed at a running Splash model. The
77
+ extension observes that model's requests exactly as it would for a directly launched Pi; it does not
78
+ inspect the launcher, parent process, or a particular provider name. If you switch to a non-Splash
79
+ (e.g. cloud) model, the stats clear immediately and subsequent requests are left untouched.
80
+ - **Pi launched directly** — configure Pi with a Splash-served OpenAI-compatible model (including a
81
+ server on a non-default port) and run Pi normally. The extension verifies the backend through the
82
+ Splash discovery protocol and shows stats while that model streams. Arbitrary configured provider
83
+ names do not prevent activation; a non-Splash provider simply shows no stats.
84
+
85
+ The extension reads no configuration, environment variables, or files, keeps no state between
86
+ invocations, and starts no background work.
87
+
88
+ ## Remove
89
+
90
+ Use `pi remove` with the same source string you installed from. Pi matches sources exactly, so
91
+ `/absolute/path`, `git:...`, and `npm:...` forms are distinct:
92
+
93
+ ```bash
94
+ pi remove /absolute/path/to/pi-splash-stats
95
+ pi remove git:github.com/cltec/pi-splash-stats
96
+ pi remove npm:@cltec/pi-splash-stats
97
+ ```
98
+
99
+ The extension keeps no configuration or state of its own. If you loaded it with `pi -e`, there is
100
+ nothing to remove.
101
+
102
+ ## Development commands
103
+
104
+ | Task | Command | Notes |
105
+ | --- | --- | --- |
106
+ | Unit, wiring, and tooling tests | `npm test` | Offline; no Pi process, no `npm pack`, no network. |
107
+ | Package check | `npm run check:package` | Asserts the `npm pack` contents. |
108
+ | Full local check | `npm run check` | `npm test && npm run check:package`. |
109
+ | End-to-end | `npm run test:e2e` | Real Pi: checkout RPC, headless JSON, packed archive. |
110
+ | One test file | `node --test test/extension.test.ts` | Replace with the file you are changing. |
111
+
112
+ `npm run check` does not run e2e. Run e2e when changing extension wiring, the command contract,
113
+ package contents, or the Pi baseline. No dependency installation is needed for any command, but
114
+ e2e needs a compatible Pi binary.
115
+
116
+ The e2e runner creates a temporary home, config directory, and working directory and passes only an
117
+ allowlisted environment. It runs Pi offline, makes no provider calls, bounds shutdown, cleans up,
118
+ and writes a sanitized schema-1 result instead of raw logs.
119
+
120
+ - **Checkout:** Pi loads `src/index.ts` with `-e`.
121
+ - **Headless JSON:** Pi runs `--mode json` and the test asserts the extension emits no custom
122
+ messages and exits cleanly.
123
+ - **Packed archive:** the runner packs the current tree, or reuses an exact checked archive via
124
+ `PACKAGE_ARCHIVE=/absolute/file.tgz`. It lists and extracts the tarball with a system `tar`, then
125
+ loads the extracted directory through a temporary Pi `settings.json` `packages` entry and discovers
126
+ the extension from the manifest. It does not run `pi install` or contact a registry; that install
127
+ path is a known coverage limit.
128
+
129
+ Set `E2E_RESULT_PATH` to change the result file. `scripts/summarize-e2e.mjs` renders only known
130
+ fields from it. See [docs/TESTING.md](docs/TESTING.md).
131
+
132
+ A separate real-Pi verification harness drives the terminal UI and non-TUI modes end to end,
133
+ including a **packed-package** journey that installs the `npm pack` artifact through the manifest.
134
+ See [`.cursor/skills/verify-pi-splash-stats/SKILL.md`](.cursor/skills/verify-pi-splash-stats/SKILL.md).
135
+
136
+ ## Packaging
137
+
138
+ `npm run check:package` treats packaging as an allowlist, not a denylist. The package ships
139
+ `package.json`, `README.md`, `LICENSE`, `CHANGELOG.md`, and non-hidden `src/**/*.ts` files, excluding
140
+ `*.test.ts`, `*.spec.ts`, and `AGENTS.md`/`CLAUDE.md`/`GEMINI.md`. Agent instructions, tests, e2e
141
+ files, docs, environment files, credentials, and tarballs must not be packed. When you add a resource
142
+ directory that users need, add it to the `files` allowlist and update the check deliberately.
143
+
144
+ ## Releases
145
+
146
+ This package is not a publishing project. It ships with `"private": true`, and the release workflow
147
+ additionally requires the `ENABLE_NPM_PUBLISH` repository variable. Releases are manual and
148
+ explicitly authorized: a reviewed pull request changes the version and `CHANGELOG.md`, then a
149
+ maintainer creates a canonical stable `vX.Y.Z` tag. There is no automatic tag on merge. Concrete,
150
+ non-placeholder repository metadata is required; `private` must also be set to `false` intentionally
151
+ before publishing.
152
+
153
+ When enabled, the workflow runs source smoke, packs the final `release/package.tgz`, re-runs e2e with
154
+ `PACKAGE_ARCHIVE` pointed at that archive, uploads the checked artifact, and publishes those same
155
+ bytes. E2E and offline steps may create temporary packs; only the final release tarball is preserved
156
+ and published. Setup, OIDC trusted publishing, and the maintainer procedure live in
157
+ [docs/RELEASING.md](docs/RELEASING.md).
158
+
159
+ ## Troubleshooting
160
+
161
+ Common local, e2e, packaging, and release-gate symptoms are listed in
162
+ [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md). Start with the failing command's own output and
163
+ the sanitized e2e artifact; do not paste credentials, prompts, or real home-directory paths into an
164
+ issue.
165
+
166
+ ## Support
167
+
168
+ - Open an issue at https://github.com/cltec/pi-splash-stats/issues for reproducible bugs and
169
+ documentation gaps.
170
+ - Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md), not in a public issue.
171
+
172
+ ## Documentation
173
+
174
+ | Document | Contents |
175
+ | --- | --- |
176
+ | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Modules, request flow, transports, modes, and failure behavior. |
177
+ | [docs/TESTING.md](docs/TESTING.md) | Test layers, e2e isolation, the real-Pi verification harness, and what is not covered. |
178
+ | [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Common local, e2e, packaging, and release-gate symptoms. |
179
+ | [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. |
180
+ | [docs/adr/0002-transport-coverage.md](docs/adr/0002-transport-coverage.md) | Why summaries use a scoped fetch observer. |
181
+ | [docs/RELEASING.md](docs/RELEASING.md) | Release setup and maintainer procedure. |
182
+ | [CONTRIBUTING.md](CONTRIBUTING.md) | Workflow, standards, and pull request checklist. |
183
+ | [AGENTS.md](AGENTS.md) | Agent instructions: verified commands, invariants, boundaries. |
184
+ | [SECURITY.md](SECURITY.md) | Reporting and security scope. |
185
+ | [CHANGELOG.md](CHANGELOG.md) | Notable changes. |
186
+
187
+ ## Security
188
+
189
+ The extension runs no external commands and reads no configuration. At runtime it makes a single
190
+ bounded, cached discovery request to the Splash backend and otherwise only observes the inference
191
+ traffic Pi already sends. Extensions run inside the Pi process with the same operating-system
192
+ permissions as Pi, so review any extension before installing it. Report vulnerabilities privately;
193
+ see [SECURITY.md](SECURITY.md).
194
+
195
+ ## License
196
+
197
+ 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.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
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
+ }
@@ -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
+ }