pi-smart-compact 7.9.2 → 7.9.3
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 +8 -0
- package/README.md +108 -438
- package/dist/constants.d.ts +1 -1
- package/dist/index.js +1 -1
- package/package.json +3 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,13 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [7.9.3] - 2026-05-18
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
- **README refocused** — Rewrote `README.md` as a concise, user-facing overview. It now explains the package in terms of agentic compaction, Kamradt-style chunking, and the EESV pipeline without repo-audit noise or drift-prone implementation snapshots.
|
|
7
|
+
- **Docs cleanup** — `DEVPLAN.md` is now positioned as an archived implementation record, `ROADMAP.md` serves as the live planning document, and new `CONTRIBUTING.md` / `ARCHITECTURE.md` files document contributor workflow and system design.
|
|
8
|
+
- **Version metadata synchronized** — `package.json`, runtime version constants, and generated `dist/` metadata now align on `7.9.3`.
|
|
9
|
+
- **TS script invocation stabilized** — `build` and `typecheck` now use `bun x tsc`, matching the working local invocation more reliably.
|
|
10
|
+
|
|
3
11
|
## [7.9.1] - 2026-05-17
|
|
4
12
|
|
|
5
13
|
### Fixed
|
package/README.md
CHANGED
|
@@ -10,391 +10,82 @@
|
|
|
10
10
|
|
|
11
11
|
> Verification-oriented smart compaction for the [Pi Coding Agent](https://github.com/earendil-works/pi-coding-agent).
|
|
12
12
|
|
|
13
|
-
`pi-smart-compact` replaces blind conversation trimming with a structured compaction pipeline that tries to preserve
|
|
13
|
+
`pi-smart-compact` replaces blind conversation trimming with a structured compaction pipeline that tries to preserve what an agent actually needs to continue working: the goal, modified files, unresolved errors, decisions, constraints, and open follow-up loops.
|
|
14
14
|
|
|
15
|
-
It
|
|
15
|
+
It uses an **EESV** pipeline:
|
|
16
16
|
|
|
17
17
|
**Extract → Explore → Synthesize → Verify**
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
Under the hood, the design is grounded in two core ideas:
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
- [What this project is](#what-this-project-is)
|
|
24
|
-
- [Current repository snapshot](#current-repository-snapshot)
|
|
25
|
-
- [Visual identity](#visual-identity)
|
|
26
|
-
- [Why it exists](#why-it-exists)
|
|
27
|
-
- [Architecture flow](#architecture-flow)
|
|
28
|
-
- [Execution model](#execution-model)
|
|
29
|
-
- [Repository layout](#repository-layout)
|
|
30
|
-
- [Runtime artifacts](#runtime-artifacts)
|
|
31
|
-
- [Installation](#installation)
|
|
32
|
-
- [Usage](#usage)
|
|
33
|
-
- [Configuration](#configuration)
|
|
34
|
-
- [Output contract](#output-contract)
|
|
35
|
-
- [Quality controls](#quality-controls)
|
|
36
|
-
- [Current caveats](#current-caveats)
|
|
37
|
-
- [Development](#development)
|
|
38
|
-
- [License](#license)
|
|
21
|
+
- **agentic compaction**: let the system inspect and reason about the session instead of collapsing everything into generic prose
|
|
22
|
+
- **Kamradt-style chunking**: break large conversations into more coherent segments before synthesis
|
|
39
23
|
|
|
40
24
|
---
|
|
41
25
|
|
|
42
26
|
## What this project is
|
|
43
27
|
|
|
44
|
-
This package is a **Pi extension**
|
|
45
|
-
|
|
46
|
-
| Surface | Where | Purpose |
|
|
47
|
-
| --- | --- | --- |
|
|
48
|
-
| Slash command | `/smart-compact` | Manual compaction, interactive or direct |
|
|
49
|
-
| Session hook | `session_before_compact` | Auto-trigger smart compaction before Pi's default compaction |
|
|
50
|
-
| Tool | `smart_compact` | Agent-callable compaction that stages a pending summary |
|
|
51
|
-
|
|
52
|
-
The extension keeps a short-lived pending compaction in memory, then hands that summary back to Pi when compaction is applied.
|
|
53
|
-
|
|
54
|
-
---
|
|
55
|
-
|
|
56
|
-
## Current repository snapshot
|
|
57
|
-
|
|
58
|
-
**Observed from the current codebase (`README`, `src/`, `test/`, `package.json`)**
|
|
59
|
-
|
|
60
|
-
- **Package version:** `7.9.1`
|
|
61
|
-
- **Runtime entrypoint:** `dist/index.js`
|
|
62
|
-
- **Source entrypoint:** `src/index.ts`
|
|
63
|
-
- **Source modules:** 18 TypeScript files under `src/`
|
|
64
|
-
- **Tests:** 9 test files, **93 passing tests**
|
|
65
|
-
- **Approx repo footprint:** ~5,091 lines across `src/` + `test/`
|
|
66
|
-
- **Documentation asset:** `docs/assets/pi-smart-compact.png`
|
|
67
|
-
- **Published package files:** `dist/`, `docs/`, `README.md`, `LICENSE`, `CHANGELOG.md`
|
|
68
|
-
|
|
69
|
-
### Current command health
|
|
70
|
-
|
|
71
|
-
| Command | Status | Notes |
|
|
72
|
-
| --- | --- | --- |
|
|
73
|
-
| `bun test` | ✅ Pass | 93/93 tests passing |
|
|
74
|
-
| `bun run build` | ✅ Pass | Bundles `src/index.ts` to `dist/index.js` |
|
|
75
|
-
| `bun run typecheck` | ✅ Pass | Strict TypeScript compatibility clean |
|
|
76
|
-
|
|
77
|
-
So the project is currently **buildable, tested, and typecheck-clean**.
|
|
78
|
-
|
|
79
|
-
---
|
|
80
|
-
|
|
81
|
-
## Visual identity
|
|
82
|
-
|
|
83
|
-
The repository image used by this `README.md` now lives at:
|
|
28
|
+
This package is a **Pi extension** with three integration surfaces:
|
|
84
29
|
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
30
|
+
| Surface | Purpose |
|
|
31
|
+
| --- | --- |
|
|
32
|
+
| `/smart-compact` | manual compaction from the chat UI |
|
|
33
|
+
| `session_before_compact` | auto-run before Pi's default compaction |
|
|
34
|
+
| `smart_compact` tool | agent-callable compaction for long sessions |
|
|
88
35
|
|
|
89
|
-
|
|
36
|
+
The extension stages a short-lived pending summary in memory, then hands it back to Pi when compaction is applied.
|
|
90
37
|
|
|
91
38
|
---
|
|
92
39
|
|
|
93
40
|
## Why it exists
|
|
94
41
|
|
|
95
|
-
Default compaction
|
|
42
|
+
Default compaction often loses the parts that matter most during coding work:
|
|
96
43
|
|
|
97
|
-
- which files were actually
|
|
44
|
+
- which files were actually changed
|
|
98
45
|
- which errors are still unresolved
|
|
99
46
|
- what the user explicitly asked for
|
|
100
47
|
- what decisions already won
|
|
101
|
-
- what
|
|
48
|
+
- what should happen next
|
|
102
49
|
|
|
103
|
-
`pi-smart-compact`
|
|
50
|
+
`pi-smart-compact` is built to preserve that operational context instead of producing a vague recap.
|
|
104
51
|
|
|
105
52
|
---
|
|
106
53
|
|
|
107
|
-
##
|
|
54
|
+
## How it works
|
|
108
55
|
|
|
109
56
|
```mermaid
|
|
110
|
-
flowchart
|
|
111
|
-
A[
|
|
112
|
-
B --> C
|
|
113
|
-
C
|
|
114
|
-
|
|
115
|
-
D --> E["Pre-processing<br/>pruneRedundant()<br/>serializeConversation()<br/>backupConversation()<br/>getPreviousCompactionContext()"]
|
|
116
|
-
E --> F["Phase 1: Extract<br/>extractStructured()<br/>files, errors, decisions, constraints,<br/>heuristic topics, timeline, goal"]
|
|
117
|
-
F --> G["Cross-session helpers<br/>load or save cached extraction<br/>deriveProjectId()<br/>loadProjectFingerprint()"]
|
|
118
|
-
G --> H{"Compacted text below singlePassMaxTokens?"}
|
|
119
|
-
H -- Yes --> I["Single-pass path<br/>singlePassCompact()"]
|
|
120
|
-
H -- No --> J{"shouldExplore()?"}
|
|
121
|
-
J -- Yes --> K["Phase 2: Explore<br/>exploreConversation()<br/>tool probe -> tool loop<br/>or direct JSON fallback"]
|
|
122
|
-
J -- No --> L["Skip exploration<br/>use heuristic boundaries only"]
|
|
123
|
-
K --> M["Merge LLM boundaries<br/>with heuristic boundaries"]
|
|
124
|
-
L --> N["chunkLlmMessages()"]
|
|
125
|
-
M --> N
|
|
126
|
-
N --> O["createBatches()<br/>provider-aware concurrency"]
|
|
127
|
-
O --> P["Phase 3: Synthesize<br/>summarizeBatch() per batch<br/>assembleLLM() or assembleFallback()"]
|
|
128
|
-
I --> Q["Phase 4: Verify<br/>verifySummary()"]
|
|
129
|
-
P --> Q
|
|
130
|
-
Q --> R{"Quality score below 85?"}
|
|
131
|
-
R -- No --> S["Accept summary"]
|
|
132
|
-
R -- Yes --> T["patchDeterministic()"]
|
|
133
|
-
T --> U{"Still below 75?"}
|
|
134
|
-
U -- No --> S
|
|
135
|
-
U -- Yes --> V["patchSummary() via LLM"]
|
|
136
|
-
V --> S
|
|
137
|
-
S --> W["Post-processing<br/>extractOpenLoops()<br/>buildCompactionState()<br/>computeDelta()<br/>inject sections"]
|
|
138
|
-
W --> X["Persist artifacts<br/>project fingerprint<br/>compaction state<br/>metrics log<br/>damage report"]
|
|
139
|
-
X --> Y["Store pending compaction<br/>in memory<br/>TTL: 5 minutes"]
|
|
140
|
-
Y --> Z["ctx.compact() now<br/>or next tree compact consumes it"]
|
|
57
|
+
flowchart LR
|
|
58
|
+
A[Extract<br/>deterministic facts] --> B[Explore<br/>optional targeted analysis]
|
|
59
|
+
B --> C[Synthesize<br/>single-pass or chunked summary]
|
|
60
|
+
C --> D[Verify<br/>score gaps and repair]
|
|
61
|
+
D --> E[Return smart compaction to Pi]
|
|
141
62
|
```
|
|
142
63
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
## Execution model
|
|
146
|
-
|
|
147
|
-
### 1. Entry and model resolution
|
|
148
|
-
|
|
149
|
-
`src/index.ts` is the extension boundary.
|
|
150
|
-
|
|
151
|
-
It does four jobs:
|
|
152
|
-
|
|
153
|
-
1. registers `/smart-compact`
|
|
154
|
-
2. registers `session_before_compact`
|
|
155
|
-
3. registers `smart_compact`
|
|
156
|
-
4. keeps a shared in-memory `pendingRef` and `isRunning` lock
|
|
157
|
-
|
|
158
|
-
Model resolution order is effectively:
|
|
159
|
-
|
|
160
|
-
- explicit command model argument, if provided
|
|
161
|
-
- configured `summaryModel`, if resolvable
|
|
162
|
-
- current session model
|
|
163
|
-
- first available model in the registry
|
|
164
|
-
|
|
165
|
-
`segmentationModel` falls back to the summary model unless explicitly configured.
|
|
166
|
-
|
|
167
|
-
### 2. Context gate and keep window
|
|
168
|
-
|
|
169
|
-
`src/core.ts` is the pipeline orchestrator.
|
|
170
|
-
|
|
171
|
-
Before compaction starts it:
|
|
172
|
-
|
|
173
|
-
- checks `MIN_TOKEN_THRESHOLD = 5000`
|
|
174
|
-
- reads the current session branch
|
|
175
|
-
- keeps the most recent tail according to the selected profile
|
|
176
|
-
- nudges the keep boundary with `smartKeepBoundary()` if adjacent messages appear to reference the same file
|
|
177
|
-
|
|
178
|
-
### 3. Pre-processing
|
|
179
|
-
|
|
180
|
-
Before any summarization, the pipeline performs:
|
|
181
|
-
|
|
182
|
-
- **redundancy pruning** via `src/utils/pruning.ts`
|
|
183
|
-
- **conversation backup** via `backupConversation()`
|
|
184
|
-
- **previous compaction context injection** via `getPreviousCompactionContext()`
|
|
185
|
-
- **incremental extraction cache lookup** via `src/utils/cache.ts`
|
|
186
|
-
- **project fingerprint lookup** via `src/utils/fingerprint.ts`
|
|
187
|
-
|
|
188
|
-
### 4. Phase 1 — Extract
|
|
189
|
-
|
|
190
|
-
`src/utils/extraction.ts` is the deterministic core.
|
|
191
|
-
|
|
192
|
-
It extracts, with zero LLM calls:
|
|
193
|
-
|
|
194
|
-
- modified files
|
|
195
|
-
- read files
|
|
196
|
-
- deleted files
|
|
197
|
-
- tool and bash-like errors
|
|
198
|
-
- retry / resolution signals
|
|
199
|
-
- explicit decisions from `ask_user`
|
|
200
|
-
- implicit user choices
|
|
201
|
-
- English and Turkish constraints
|
|
202
|
-
- heuristic topic segments
|
|
203
|
-
- timeline events
|
|
204
|
-
- main goal
|
|
205
|
-
- recent user messages
|
|
206
|
-
- recent error snippets
|
|
207
|
-
|
|
208
|
-
It also builds **open loops** from:
|
|
209
|
-
|
|
210
|
-
- unresolved errors
|
|
211
|
-
- follow-up language
|
|
212
|
-
- blocked/waiting language
|
|
213
|
-
- retried-but-unresolved failures
|
|
214
|
-
|
|
215
|
-
### 5. Phase 2 — Explore
|
|
216
|
-
|
|
217
|
-
`src/phases/explore.ts` adds targeted LLM exploration only when complexity justifies it.
|
|
218
|
-
|
|
219
|
-
Exploration is skipped for simple sessions when the extraction stays below these heuristics:
|
|
220
|
-
|
|
221
|
-
- `<= 3` topics
|
|
222
|
-
- `<= 1` unresolved error
|
|
223
|
-
- `<= 2` decisions
|
|
224
|
-
- `<= 2` directory groups touched
|
|
225
|
-
|
|
226
|
-
If exploration runs, it can use these tools:
|
|
227
|
-
|
|
228
|
-
- `get_message_range`
|
|
229
|
-
- `search_conversation`
|
|
230
|
-
- `get_recent_user_messages`
|
|
231
|
-
- `get_context_around`
|
|
232
|
-
- `get_file_changes`
|
|
233
|
-
- `get_error_chain`
|
|
234
|
-
|
|
235
|
-
If the provider cannot or does not use tools, exploration falls back to a direct JSON analysis prompt.
|
|
236
|
-
|
|
237
|
-
### 6. Phase 3 — Synthesize
|
|
238
|
-
|
|
239
|
-
`src/phases/synthesize.ts` supports two paths:
|
|
240
|
-
|
|
241
|
-
#### Single-pass
|
|
242
|
-
Used when the pruned conversation fits under the profile's `singlePassMaxTokens`.
|
|
243
|
-
|
|
244
|
-
#### Hierarchical
|
|
245
|
-
Used for larger sessions:
|
|
246
|
-
|
|
247
|
-
- merge heuristic and exploratory boundaries
|
|
248
|
-
- chunk messages with `chunkLlmMessages()`
|
|
249
|
-
- batch chunks with `createBatches()`
|
|
250
|
-
- summarize each batch with `summarizeBatch()`
|
|
251
|
-
- assemble a final summary with `assembleLLM()`
|
|
252
|
-
- fall back to `assembleFallback()` if assembly fails
|
|
253
|
-
|
|
254
|
-
Important synthesis behaviors already present in code:
|
|
255
|
-
|
|
256
|
-
- **decision propagation** into later batch prompts
|
|
257
|
-
- **session-type-specific prompting**
|
|
258
|
-
- **topic-level budget hints** during assembly pre-processing
|
|
259
|
-
- **provider-aware batch concurrency** from `src/utils/tokens.ts`
|
|
260
|
-
|
|
261
|
-
### 7. Phase 4 — Verify
|
|
262
|
-
|
|
263
|
-
`src/phases/verify.ts` scores the summary against deterministic extraction data.
|
|
264
|
-
|
|
265
|
-
It checks for:
|
|
266
|
-
|
|
267
|
-
- missing modified files
|
|
268
|
-
- missing unresolved errors
|
|
269
|
-
- missing high-confidence constraints
|
|
270
|
-
- missing goal coverage
|
|
271
|
-
- missing required sections
|
|
272
|
-
- suspicious fabricated file references
|
|
273
|
-
- done/unresolved inconsistency
|
|
274
|
-
- missing explicit decisions
|
|
275
|
-
- missing open-loop coverage when unresolved errors exist
|
|
276
|
-
|
|
277
|
-
Repair strategy is intentionally ordered:
|
|
278
|
-
|
|
279
|
-
1. no patch if score is acceptable
|
|
280
|
-
2. deterministic patch first
|
|
281
|
-
3. LLM patch only if deterministic patch is insufficient
|
|
282
|
-
|
|
283
|
-
### 8. Post-processing and persistence
|
|
284
|
-
|
|
285
|
-
After verification, the pipeline:
|
|
286
|
-
|
|
287
|
-
- extracts open loops
|
|
288
|
-
- injects `## Open Loops`
|
|
289
|
-
- builds a machine-readable `CompactionState`
|
|
290
|
-
- loads previous compaction state
|
|
291
|
-
- computes delta across compactions
|
|
292
|
-
- injects `## Changes Since Last Compaction`
|
|
293
|
-
- saves project fingerprint
|
|
294
|
-
- saves compaction state
|
|
295
|
-
- appends metrics log
|
|
296
|
-
- attempts post-compaction damage detection
|
|
297
|
-
|
|
298
|
-
### 9. Applying compaction
|
|
299
|
-
|
|
300
|
-
The extension stores the result in an in-memory pending object containing:
|
|
301
|
-
|
|
302
|
-
- summary
|
|
303
|
-
- first kept entry id
|
|
304
|
-
- tokens before compaction
|
|
305
|
-
- details payload
|
|
306
|
-
- structured compaction state
|
|
64
|
+
### Pipeline summary
|
|
307
65
|
|
|
308
|
-
|
|
66
|
+
1. **Extract**
|
|
67
|
+
- deterministically pulls files, errors, decisions, constraints, topics, and open loops from the session
|
|
68
|
+
2. **Explore**
|
|
69
|
+
- optionally inspects the conversation more deeply when the session is complex
|
|
70
|
+
3. **Synthesize**
|
|
71
|
+
- creates either a single-pass summary or a chunked hierarchical summary
|
|
72
|
+
4. **Verify**
|
|
73
|
+
- checks the result against extracted facts and patches missing critical details
|
|
309
74
|
|
|
310
|
-
|
|
311
|
-
- the next `session_before_compact` hook call in tool-driven flows
|
|
75
|
+
In short: **facts first, synthesis second, verification last**.
|
|
312
76
|
|
|
313
77
|
---
|
|
314
78
|
|
|
315
|
-
##
|
|
316
|
-
|
|
317
|
-
### Top-level
|
|
79
|
+
## What it tries to preserve
|
|
318
80
|
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
├── docs/
|
|
328
|
-
│ └── assets/
|
|
329
|
-
│ └── pi-smart-compact.png
|
|
330
|
-
├── package.json
|
|
331
|
-
├── src/
|
|
332
|
-
├── test/
|
|
333
|
-
└── tsconfig.json
|
|
334
|
-
```
|
|
335
|
-
|
|
336
|
-
### Source modules
|
|
337
|
-
|
|
338
|
-
| File | Role |
|
|
339
|
-
| --- | --- |
|
|
340
|
-
| `src/index.ts` | Extension registration: command, hook, tool |
|
|
341
|
-
| `src/core.ts` | End-to-end pipeline orchestration |
|
|
342
|
-
| `src/constants.ts` | Version, prompts, profiles, thresholds, config keys |
|
|
343
|
-
| `src/types.ts` | Shared types and guards |
|
|
344
|
-
| `src/phases/explore.ts` | Exploration phase, tool loop, JSON fallback |
|
|
345
|
-
| `src/phases/synthesize.ts` | Chunking, batching, single-pass and hierarchical synthesis |
|
|
346
|
-
| `src/phases/verify.ts` | Verification, deterministic patch, LLM patch |
|
|
347
|
-
| `src/ui/overlays.ts` | 2-step picker UI, progress notices, result screen |
|
|
348
|
-
| `src/utils/cache.ts` | Metrics, cache-aware LLM options, extraction cache |
|
|
349
|
-
| `src/utils/damage.ts` | Post-compaction regression signal detection |
|
|
350
|
-
| `src/utils/extraction.ts` | Deterministic extraction and open-loop detection |
|
|
351
|
-
| `src/utils/logger.ts` | Centralized logging with shared prefix |
|
|
352
|
-
| `src/utils/fingerprint.ts` | Cross-session project fingerprinting |
|
|
353
|
-
| `src/utils/helpers.ts` | Config loading, backups, batching, prompt helpers |
|
|
354
|
-
| `src/utils/pruning.ts` | Redundancy pruning before compaction |
|
|
355
|
-
| `src/utils/state.ts` | Compaction state persistence and delta logic |
|
|
356
|
-
| `src/utils/tokens.ts` | Provider capabilities and token estimation |
|
|
357
|
-
| `src/utils/type-guards.ts` | Shared type guard functions |
|
|
358
|
-
|
|
359
|
-
### Tests
|
|
360
|
-
|
|
361
|
-
| Test file | Coverage |
|
|
362
|
-
| --- | --- |
|
|
363
|
-
| `test/extraction.test.ts` | deterministic extraction |
|
|
364
|
-
| `test/exploration.test.ts` | exploration parsing and gating |
|
|
365
|
-
| `test/eval.test.ts` | gold scenarios, delta evaluation, fabrication safety |
|
|
366
|
-
| `test/fingerprint.test.ts` | project fingerprint helpers |
|
|
367
|
-
| `test/pruning.test.ts` | redundancy pruning |
|
|
368
|
-
| `test/semantic-compact.test.ts` | legacy-name regression coverage |
|
|
369
|
-
| `test/state.test.ts` | open loops, state, delta, persistence |
|
|
370
|
-
| `test/tokens.test.ts` | token estimation and provider caps |
|
|
371
|
-
| `test/verify.test.ts` | verification and patching |
|
|
372
|
-
|
|
373
|
-
---
|
|
374
|
-
|
|
375
|
-
## Runtime artifacts
|
|
376
|
-
|
|
377
|
-
The current code writes to these paths at runtime:
|
|
378
|
-
|
|
379
|
-
| Artifact | Path |
|
|
380
|
-
| --- | --- |
|
|
381
|
-
| Settings file | `~/.pi/agent/settings.json` |
|
|
382
|
-
| Conversation backups | `~/.pi/agent/compact-backups/` |
|
|
383
|
-
| Extraction cache | `~/.pi/agent/.cache/compact-extraction-<session>.json` |
|
|
384
|
-
| Metrics log | `~/.pi/agent/.cache/compact-metrics.jsonl` |
|
|
385
|
-
| Project fingerprints | `~/.pi/agent/.cache/smart-compact/projects/<projectId>.json` |
|
|
386
|
-
| Compaction states | `~/.pi/agent/.cache/smart-compact/states/<projectId>.json` |
|
|
387
|
-
| Damage reports | `~/.pi/agent/.cache/smart-compact/damage-reports.jsonl` |
|
|
388
|
-
|
|
389
|
-
### TTLs currently implemented
|
|
390
|
-
|
|
391
|
-
| Item | TTL |
|
|
392
|
-
| --- | --- |
|
|
393
|
-
| pending in-memory compaction | 5 minutes |
|
|
394
|
-
| exploration tool-support cache | 30 minutes |
|
|
395
|
-
| extraction cache | 1 hour |
|
|
396
|
-
| compaction state | 7 days |
|
|
397
|
-
| project fingerprint | 30 days |
|
|
81
|
+
- user goal
|
|
82
|
+
- constraints and preferences
|
|
83
|
+
- modified / read / deleted files
|
|
84
|
+
- unresolved and resolved errors
|
|
85
|
+
- key decisions
|
|
86
|
+
- open follow-up work
|
|
87
|
+
- critical context needed for the next turn
|
|
88
|
+
- delta from the previous compaction
|
|
398
89
|
|
|
399
90
|
---
|
|
400
91
|
|
|
@@ -424,7 +115,7 @@ bun run build
|
|
|
424
115
|
|
|
425
116
|
---
|
|
426
117
|
|
|
427
|
-
##
|
|
118
|
+
## Quick start
|
|
428
119
|
|
|
429
120
|
### Interactive
|
|
430
121
|
|
|
@@ -432,10 +123,10 @@ bun run build
|
|
|
432
123
|
/smart-compact
|
|
433
124
|
```
|
|
434
125
|
|
|
435
|
-
With no arguments, the extension opens a
|
|
126
|
+
With no arguments, the extension opens a small picker for:
|
|
436
127
|
|
|
437
|
-
1. model
|
|
438
|
-
2. profile
|
|
128
|
+
1. model
|
|
129
|
+
2. profile
|
|
439
130
|
|
|
440
131
|
### Direct command examples
|
|
441
132
|
|
|
@@ -446,13 +137,6 @@ With no arguments, the extension opens a **2-step TUI**:
|
|
|
446
137
|
/smart-compact "focus on auth changes and unresolved follow-up work"
|
|
447
138
|
```
|
|
448
139
|
|
|
449
|
-
Argument parsing in the current code supports:
|
|
450
|
-
|
|
451
|
-
- model ids containing `/`
|
|
452
|
-
- profiles: `light`, `balanced`, `aggressive`
|
|
453
|
-
- flags: `verbose`, `debug`, `dry-run`
|
|
454
|
-
- remaining free text as a user steering note
|
|
455
|
-
|
|
456
140
|
### Tool usage
|
|
457
141
|
|
|
458
142
|
```json
|
|
@@ -466,11 +150,18 @@ Argument parsing in the current code supports:
|
|
|
466
150
|
}
|
|
467
151
|
```
|
|
468
152
|
|
|
469
|
-
|
|
153
|
+
The tool prepares a pending smart summary and lets Pi consume it on the next natural compaction.
|
|
470
154
|
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## Usage notes
|
|
158
|
+
|
|
159
|
+
- compaction is skipped when the context is still small enough
|
|
160
|
+
- the tool path does **not** compact the conversation mid-turn
|
|
161
|
+
- pending summaries are kept in memory for **5 minutes**
|
|
162
|
+
- exploration is adaptive and may be skipped for simple sessions
|
|
163
|
+
|
|
164
|
+
This keeps the extension helpful without forcing extra work when it is not needed.
|
|
474
165
|
|
|
475
166
|
---
|
|
476
167
|
|
|
@@ -508,29 +199,23 @@ Add this to `~/.pi/agent/settings.json`:
|
|
|
508
199
|
| `backupDir` | `string` | `~/.pi/agent/compact-backups` |
|
|
509
200
|
| `profiles` | partial per-profile overrides | built-ins |
|
|
510
201
|
|
|
511
|
-
### Profiles
|
|
202
|
+
### Profiles
|
|
512
203
|
|
|
513
|
-
| Profile | Summary budget | Keep recent |
|
|
514
|
-
| --- | ---: | ---: |
|
|
515
|
-
| `light` | 10000 | 30000 |
|
|
516
|
-
| `balanced` | 6000 | 20000 |
|
|
517
|
-
| `aggressive` | 3000 | 10000 |
|
|
204
|
+
| Profile | Summary budget | Keep recent | Typical use |
|
|
205
|
+
| --- | ---: | ---: | --- |
|
|
206
|
+
| `light` | 10000 | 30000 | preserve more detail |
|
|
207
|
+
| `balanced` | 6000 | 20000 | default general use |
|
|
208
|
+
| `aggressive` | 3000 | 10000 | tighter summaries |
|
|
518
209
|
|
|
519
210
|
### Backward compatibility
|
|
520
211
|
|
|
521
|
-
The
|
|
522
|
-
|
|
523
|
-
- `semanticCompact`
|
|
524
|
-
|
|
525
|
-
but the current key is:
|
|
526
|
-
|
|
527
|
-
- `smartCompact`
|
|
212
|
+
The extension still accepts the old config key `semanticCompact`, but `smartCompact` is the current key.
|
|
528
213
|
|
|
529
214
|
---
|
|
530
215
|
|
|
531
216
|
## Output contract
|
|
532
217
|
|
|
533
|
-
|
|
218
|
+
Generated summaries are expected to use this structure:
|
|
534
219
|
|
|
535
220
|
```markdown
|
|
536
221
|
## Goal
|
|
@@ -549,94 +234,79 @@ The generated Markdown is expected to follow this structure:
|
|
|
549
234
|
## Topics Covered
|
|
550
235
|
```
|
|
551
236
|
|
|
552
|
-
The extension also builds a structured `CompactionState`
|
|
553
|
-
|
|
554
|
-
- goal
|
|
555
|
-
- decisions
|
|
556
|
-
- constraints
|
|
557
|
-
- modified/read/deleted files
|
|
558
|
-
- unresolved/resolved errors
|
|
559
|
-
- open loops
|
|
560
|
-
- topics
|
|
561
|
-
- next actions
|
|
562
|
-
- critical context
|
|
563
|
-
- session type
|
|
564
|
-
- compaction version
|
|
565
|
-
|
|
566
|
-
This state is persisted on disk and reused for delta tracking on later compactions.
|
|
237
|
+
The extension also builds a structured `CompactionState` for reuse across later compactions.
|
|
567
238
|
|
|
568
239
|
---
|
|
569
240
|
|
|
570
|
-
##
|
|
241
|
+
## Safeguards
|
|
571
242
|
|
|
572
|
-
The current
|
|
243
|
+
The current design includes:
|
|
573
244
|
|
|
574
|
-
- deterministic extraction before
|
|
575
|
-
- adaptive exploration
|
|
576
|
-
-
|
|
577
|
-
- incremental extraction cache
|
|
578
|
-
- provider-aware token estimation and concurrency
|
|
245
|
+
- deterministic extraction before summarization
|
|
246
|
+
- adaptive exploration
|
|
247
|
+
- chunked synthesis for larger sessions
|
|
579
248
|
- deterministic verification scoring
|
|
580
|
-
- deterministic
|
|
249
|
+
- deterministic patching before LLM patching
|
|
581
250
|
- hallucinated file-reference detection
|
|
582
251
|
- open-loop injection
|
|
583
|
-
-
|
|
584
|
-
- post-compaction damage detection
|
|
252
|
+
- project fingerprinting and delta tracking
|
|
585
253
|
- backup creation before compaction
|
|
586
|
-
- metrics logging
|
|
254
|
+
- metrics logging and damage detection
|
|
587
255
|
|
|
588
256
|
---
|
|
589
257
|
|
|
590
|
-
##
|
|
258
|
+
## Runtime artifacts
|
|
591
259
|
|
|
592
|
-
|
|
260
|
+
At runtime, the extension writes to paths under `~/.pi/agent/`, including:
|
|
593
261
|
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
262
|
+
- `settings.json`
|
|
263
|
+
- `compact-backups/`
|
|
264
|
+
- `.cache/compact-extraction-<session>.json`
|
|
265
|
+
- `.cache/compact-metrics.jsonl`
|
|
266
|
+
- `.cache/smart-compact/projects/<projectId>.json`
|
|
267
|
+
- `.cache/smart-compact/states/<projectId>.json`
|
|
268
|
+
- `.cache/smart-compact/damage-reports.jsonl`
|
|
597
269
|
|
|
598
270
|
---
|
|
599
271
|
|
|
600
|
-
##
|
|
601
|
-
|
|
602
|
-
### Install
|
|
272
|
+
## Repository layout
|
|
603
273
|
|
|
604
|
-
```
|
|
605
|
-
|
|
274
|
+
```text
|
|
275
|
+
.
|
|
276
|
+
├── src/
|
|
277
|
+
│ ├── index.ts
|
|
278
|
+
│ ├── core.ts
|
|
279
|
+
│ ├── phases/
|
|
280
|
+
│ ├── ui/
|
|
281
|
+
│ └── utils/
|
|
282
|
+
├── test/
|
|
283
|
+
├── docs/
|
|
284
|
+
├── dist/
|
|
285
|
+
└── package.json
|
|
606
286
|
```
|
|
607
287
|
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
```bash
|
|
611
|
-
bun test
|
|
612
|
-
bun test test/eval.test.ts
|
|
613
|
-
```
|
|
288
|
+
---
|
|
614
289
|
|
|
615
|
-
|
|
290
|
+
## Development
|
|
616
291
|
|
|
617
292
|
```bash
|
|
293
|
+
bun install
|
|
294
|
+
bun test
|
|
618
295
|
bun run build
|
|
619
|
-
```
|
|
620
|
-
|
|
621
|
-
Current build command:
|
|
622
|
-
|
|
623
|
-
```bash
|
|
624
|
-
rm -rf dist && mkdir dist && bun build ./src/index.ts --outdir ./dist --target bun --external '@earendil-works/*' --external 'typebox'
|
|
625
|
-
```
|
|
626
|
-
|
|
627
|
-
### Typecheck
|
|
628
|
-
|
|
629
|
-
```bash
|
|
630
296
|
bun run typecheck
|
|
631
297
|
```
|
|
632
298
|
|
|
633
|
-
|
|
299
|
+
Build output is published from `dist/`.
|
|
634
300
|
|
|
635
|
-
|
|
301
|
+
---
|
|
636
302
|
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
303
|
+
## Project docs
|
|
304
|
+
|
|
305
|
+
- [`CHANGELOG.md`](./CHANGELOG.md) — release history
|
|
306
|
+
- [`ARCHITECTURE.md`](./ARCHITECTURE.md) — system design and execution model
|
|
307
|
+
- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — contributor workflow and expectations
|
|
308
|
+
- [`ROADMAP.md`](./ROADMAP.md) — current priorities
|
|
309
|
+
- [`DEVPLAN.md`](./DEVPLAN.md) — archived implementation plan
|
|
640
310
|
|
|
641
311
|
---
|
|
642
312
|
|
package/dist/constants.d.ts
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* Constants, prompts, and profile defaults.
|
|
3
3
|
*/
|
|
4
4
|
import type { CompressionProfile, ProfileConfig } from "./types.ts";
|
|
5
|
-
export declare const VERSION = "7.9.
|
|
5
|
+
export declare const VERSION = "7.9.3";
|
|
6
6
|
export declare const CHARS_PER_TOKEN = 3.8;
|
|
7
7
|
export declare const COMPACT_SYSTEM_PREFIX: string;
|
|
8
8
|
export declare const PROFILES: Record<CompressionProfile, ProfileConfig>;
|
package/dist/index.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
// @bun
|
|
2
2
|
// src/constants.ts
|
|
3
|
-
var VERSION = "7.9.
|
|
3
|
+
var VERSION = "7.9.3";
|
|
4
4
|
var CHARS_PER_TOKEN = 3.8;
|
|
5
5
|
var COMPACT_SYSTEM_PREFIX = "You are an expert conversation summarizer for a coding agent. " + "Produce structured markdown summaries. " + "Follow output format exactly. " + "Use EXACT names \u2014 never paraphrase code identifiers. " + "Trust deterministic extraction data over intuition.";
|
|
6
6
|
var PROFILES = {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-smart-compact",
|
|
3
|
-
"version": "7.9.
|
|
3
|
+
"version": "7.9.3",
|
|
4
4
|
"description": "EESV smart compaction extension for Pi Coding Agent — deterministic extraction, exploration, synthesis, verification with redundancy pruning, project fingerprinting, and damage detection.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -40,9 +40,9 @@
|
|
|
40
40
|
"CHANGELOG.md"
|
|
41
41
|
],
|
|
42
42
|
"scripts": {
|
|
43
|
-
"build": "rm -rf dist && mkdir dist && bun build ./src/index.ts --outdir ./dist --target bun --external '@earendil-works/*' --external 'typebox' &&
|
|
43
|
+
"build": "rm -rf dist && mkdir dist && bun build ./src/index.ts --outdir ./dist --target bun --external '@earendil-works/*' --external 'typebox' && bun x tsc --emitDeclarationOnly --outDir dist",
|
|
44
44
|
"test": "bun test",
|
|
45
|
-
"typecheck": "
|
|
45
|
+
"typecheck": "bun x tsc --noEmit"
|
|
46
46
|
},
|
|
47
47
|
"pi": {
|
|
48
48
|
"extensions": ["./dist/index.js"]
|