@nijaru/pi-provider-compaction 0.0.2 → 0.0.4
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/README.md +55 -41
- package/dist/index.js +1983 -0
- package/index.ts +279 -456
- package/package.json +13 -11
- package/protocol.ts +50 -12
- package/provider.ts +85 -0
- package/replay.ts +140 -0
package/README.md
CHANGED
|
@@ -1,84 +1,98 @@
|
|
|
1
1
|
# pi-provider-compaction
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Experimental provider-native compaction for [Pi](https://github.com/earendil-works/pi), with a meaningful portable summary saved alongside each native checkpoint. Requires Pi 0.87.0.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**The unpublished redesign is not production-validated. Do not enable it globally yet.** Real runner/adapter fixtures and a Codex live smoke test pass; broader backend and deployment validation remains incomplete.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
[pi-compactor](https://github.com/nijaru/pi-compactor) owns compaction timing and continuation. This extension owns native request capture, prefix coverage, persistence and replay. It does not change `/fast` or account reporting.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
## Supported integration
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
Pi 0.87.0 has replacement provider registration, not composable middleware. This extension only installs request observation where it can preserve the existing provider contract:
|
|
12
|
+
|
|
13
|
+
- **Registered native base providers:** both streaming methods are decorated; authentication, catalogs, filtering, refresh and deferred methods stay with the original provider. `models.json` remains above that base.
|
|
14
|
+
- **Existing static legacy `streamSimple` registrations:** the original callback and configuration are retained. This includes `pi-fast-mode`'s Codex registration. Legacy dynamic catalogs and OAuth model-projection callbacks are excluded.
|
|
15
|
+
- **Plain built-in providers and other unsupported registrations:** portable Pi compaction only. Injecting a legacy wrapper here would silently change full-stream calls into simple-stream calls.
|
|
16
|
+
|
|
17
|
+
For an eligible request, protocol selection is automatic:
|
|
18
|
+
|
|
19
|
+
| Pi API | Native protocol |
|
|
12
20
|
| --- | --- |
|
|
13
|
-
| `openai-responses` |
|
|
14
|
-
| `azure-openai-responses` |
|
|
15
|
-
| `openai-codex-responses` | Codex Remote V2
|
|
16
|
-
| other APIs | Not claimed; Pi's normal compaction remains available |
|
|
21
|
+
| `openai-responses` | `POST .../responses/compact` |
|
|
22
|
+
| `azure-openai-responses` | The same endpoint, preserving Pi's Azure URL/query/auth |
|
|
23
|
+
| `openai-codex-responses` | Codex Remote V2 using `compaction_trigger` |
|
|
17
24
|
|
|
18
|
-
|
|
25
|
+
An API name does not prove its backend supports that protocol. Failed attempts return the already-produced portable summary; no other provider or protocol is probed. In-stream `context_management` remains unsupported.
|
|
19
26
|
|
|
20
|
-
|
|
27
|
+
## Coverage and replay
|
|
21
28
|
|
|
22
|
-
|
|
29
|
+
Native state covers **only the prefix summarized by Pi**, ending before `firstKeptEntryId`. It does not cover retained recent messages.
|
|
23
30
|
|
|
24
|
-
A
|
|
31
|
+
The extension captures a bounded, fully prepared request after Pi's payload hooks finish. An exact serializer validator proves the covered prefix and a closed tool-exchange boundary. Native input comes from that captured request—not reconstructed persisted history. A recent capture may omit the latest assistant response if that response is retained rather than summarized. Captures expire after five minutes and are limited to 8 MiB of context plus payload.
|
|
25
32
|
|
|
26
|
-
|
|
27
|
-
2. the meaningful text summary Pi would normally save.
|
|
33
|
+
Replay replaces exactly one validated portable-summary contribution with the native output window. Retained and new messages, instructions, tools and other request fields remain from the actual request. No live suffix is rebuilt.
|
|
28
34
|
|
|
29
|
-
|
|
35
|
+
Request-only suffix additions, deletions, redactions and reordering can survive replay. Authentication must match the actual request; unmatched header/environment transformations disable native eligibility. Unmapped changes to the covered prefix or summary, payload-input rewrites, ambiguous summary matches, serializer drift and unsafe tool boundaries instead leave the portable request untouched. Codex top-level `instructions` and OpenAI/Azure input prompt items are handled separately.
|
|
30
36
|
|
|
31
|
-
|
|
37
|
+
## Safety and persistence
|
|
32
38
|
|
|
33
|
-
Version
|
|
39
|
+
Version 3 stores the portable summary, native output, usage, route identity and validated prefix metadata in one compaction entry. Both generation requests contribute to usage accounting. Raw credentials, complete auth headers and request snapshots are never persisted.
|
|
34
40
|
|
|
35
|
-
|
|
41
|
+
Native eligibility is deliberately **session-local and short-lived**. Restart, reload, resume, fork, tree navigation, model changes, covered-history edits, and relevant prompt/tool/route changes revoke it. A credential refresh may conservatively revoke it too. Persisted native metadata alone is not authority to replay hidden content under a new runtime's privacy policy.
|
|
36
42
|
|
|
37
|
-
|
|
43
|
+
Dynamic privacy policies that can change what previously covered history is allowed to reveal are **not transparently supported**. A cooperating policy owner must emit `pi-provider-compaction:invalidate` before such a change; otherwise keep this extension disabled. Matching visible summary text cannot establish that hidden native state obeys a new policy.
|
|
38
44
|
|
|
39
|
-
|
|
40
|
-
2. trusted `.pi/compaction-policy.json`; then
|
|
41
|
-
3. agent `compaction-policy.json`.
|
|
45
|
+
Portable fallback means Pi's ordinary behavior, **not universal redaction protection**: Pi's built-in summarizer does not inherit request-time context/payload hooks.
|
|
42
46
|
|
|
43
|
-
|
|
47
|
+
Legacy v1/v2 whole-history checkpoints remain inspectable but are never reinterpreted as prefix-only state. Version 2 has a portable summary. Version 1's opaque placeholder does not; the extension warns rather than pretending that missing history is recoverable from the placeholder. Recover from earlier session history or begin a new session.
|
|
44
48
|
|
|
45
|
-
##
|
|
49
|
+
## Diagnose portable fallback
|
|
46
50
|
|
|
47
|
-
|
|
51
|
+
Run `/provider-compaction-status` to see whether the observer is installed, the latest capture status, and the last compaction attempt in this runtime. Portable fallback also appends a `pi-provider-compaction:diagnostic` session entry containing only a fixed reason string. It is not included in model context. Diagnostics never include request content, credentials, or backend error text.
|
|
48
52
|
|
|
49
|
-
|
|
53
|
+
These diagnostics require the extension to be loaded when the attempt happens; they cannot explain earlier compactions retroactively. A committed native checkpoint does not by itself prove that a later request replayed it.
|
|
50
54
|
|
|
51
|
-
##
|
|
55
|
+
## Generic compaction-model override
|
|
52
56
|
|
|
53
|
-
|
|
57
|
+
An explicit generic model takes precedence, matching `pi-compactor`:
|
|
54
58
|
|
|
55
|
-
|
|
59
|
+
1. `--compaction-model ...`;
|
|
60
|
+
2. trusted `.pi/compaction-policy.json`;
|
|
61
|
+
3. agent `compaction-policy.json`.
|
|
56
62
|
|
|
57
|
-
|
|
63
|
+
An empty `models` list is not an override.
|
|
64
|
+
|
|
65
|
+
## Local development
|
|
58
66
|
|
|
59
67
|
```bash
|
|
60
|
-
|
|
68
|
+
bun install
|
|
69
|
+
bun run check
|
|
70
|
+
bun run build
|
|
71
|
+
pi --extension ./dist/index.js
|
|
61
72
|
```
|
|
62
73
|
|
|
63
|
-
|
|
74
|
+
The manifest loads the built `dist/index.js`; source edits alone do not update it. Keep global installation disabled while testing. Publishing and global activation are separate approval steps.
|
|
64
75
|
|
|
65
|
-
|
|
76
|
+
Tests include real Pi 0.87.0 runner/adapter fixtures for all three protocols, repeated prefix compaction, transformed suffix preservation, unchanged fallback, grammar tools, strict defaults, tool IDs, images and prompt updates. The optional installed-fast-mode fixture (`PI_FAST_MODE_FIXTURE_PATH`) also checks actual `pi-fast-mode` composition across `/reload`; run it with an isolated `PI_CODING_AGENT_DIR` containing an active, persistent fast-mode configuration.
|
|
77
|
+
|
|
78
|
+
Authenticated protocol smoke tests are separate and send three small requests:
|
|
66
79
|
|
|
67
80
|
```bash
|
|
68
|
-
bun
|
|
69
|
-
bun run check
|
|
81
|
+
bun run tests/live-smoke.ts openai-codex gpt-5.5
|
|
70
82
|
```
|
|
71
83
|
|
|
72
|
-
|
|
84
|
+
Validation on 2026-09-22:
|
|
73
85
|
|
|
74
|
-
|
|
86
|
+
- **Codex `gpt-5.5`:** prefix-only Remote V2 compaction and continuation accepted; an exact code held only in the summarized assistant message was recalled.
|
|
87
|
+
- **Direct OpenAI `gpt-5.5`:** initial request failed; compact/continuation remain unverified.
|
|
88
|
+
- **Azure:** no configured credentials; fixtures only.
|
|
75
89
|
|
|
76
|
-
The
|
|
90
|
+
The installed `pi-fast-mode` 0.0.2 composition/reload fixture passed separately. These checks do not establish transparent arbitrary-hook support or production readiness.
|
|
77
91
|
|
|
78
92
|
## Related extensions
|
|
79
93
|
|
|
80
|
-
- [pi-compactor](https://github.com/nijaru/pi-compactor):
|
|
81
|
-
- [pi-fast-mode](https://github.com/nijaru/pi-fast-mode): `/fast` and
|
|
94
|
+
- [pi-compactor](https://github.com/nijaru/pi-compactor): timing and continuation.
|
|
95
|
+
- [pi-fast-mode](https://github.com/nijaru/pi-fast-mode): `/fast` and service-tier policy.
|
|
82
96
|
- [pi-usage](https://github.com/nijaru/pi-usage): read-only balances and quota reporting.
|
|
83
97
|
|
|
84
98
|
## License
|