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 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 the agent's working state: goal, files, errors, decisions, constraints, open loops, and cross-compaction deltas.
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 is built around an **EESV** pipeline:
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
- ## Table of Contents
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** that registers three integration surfaces:
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
- - `docs/assets/pi-smart-compact.png`
86
-
87
- The asset is now a cleaned transparent `PNG` instead of a checkerboard/transparent-preview render, so it displays correctly inside GitHub `README.md`.
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
- This keeps documentation assets separate from `src/` implementation code and `test/` fixtures while still shipping the image with the package via `package.json` `files`.
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 usually loses exactly the things a coding agent needs most:
42
+ Default compaction often loses the parts that matter most during coding work:
96
43
 
97
- - which files were actually modified
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 still needs to happen next
48
+ - what should happen next
102
49
 
103
- `pi-smart-compact` tries to preserve that operational state instead of producing a generic prose summary.
50
+ `pi-smart-compact` is built to preserve that operational context instead of producing a vague recap.
104
51
 
105
52
  ---
106
53
 
107
- ## Architecture flow
54
+ ## How it works
108
55
 
109
56
  ```mermaid
110
- flowchart TD
111
- A["Entry points<br/>/smart-compact<br/>session_before_compact<br/>smart_compact tool"] --> B["Load config and resolve models<br/>loadConfig()<br/>summaryModel / segmentationModel"]
112
- B --> C{"Context >= 5000 tokens?"}
113
- C -- No --> C1["Exit early"]
114
- C -- Yes --> D["Read current branch<br/>keep recent tail by profile<br/>smartKeepBoundary()"]
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
- That pending summary is valid for **5 minutes** and is consumed by:
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
- - immediate `ctx.compact()` in the slash-command flow, or
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
- ## Repository layout
316
-
317
- ### Top-level
79
+ ## What it tries to preserve
318
80
 
319
- ```text
320
- .
321
- ├── CHANGELOG.md
322
- ├── DEVPLAN.md
323
- ├── LICENSE
324
- ├── README.md
325
- ├── dist/
326
- │ └── index.js
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
- ## Usage
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 **2-step TUI**:
126
+ With no arguments, the extension opens a small picker for:
436
127
 
437
- 1. model selection
438
- 2. profile selection
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
- Tool behavior is slightly different from the slash command:
153
+ The tool prepares a pending smart summary and lets Pi consume it on the next natural compaction.
470
154
 
471
- - it generates a pending smart summary
472
- - it does **not** immediately compact when `skipCompact` is used internally
473
- - it expects the next tree compaction to consume the pending result within 5 minutes
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 currently shipped
202
+ ### Profiles
512
203
 
513
- | Profile | Summary budget | Keep recent | Min chunk | Max chunk | Single-pass max | Batch max |
514
- | --- | ---: | ---: | ---: | ---: | ---: | ---: |
515
- | `light` | 10000 | 30000 | 800 | 12000 | 40000 | 30000 |
516
- | `balanced` | 6000 | 20000 | 500 | 8000 | 30000 | 24000 |
517
- | `aggressive` | 3000 | 10000 | 300 | 6000 | 20000 | 18000 |
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 code still accepts the old config key:
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
- The generated Markdown is expected to follow this structure:
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` object containing:
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
- ## Quality controls
241
+ ## Safeguards
571
242
 
572
- The current codebase includes these safeguards:
243
+ The current design includes:
573
244
 
574
- - deterministic extraction before any summarization
575
- - adaptive exploration skip for simple sessions
576
- - project fingerprint reuse across sessions
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 patch before LLM patch
249
+ - deterministic patching before LLM patching
581
250
  - hallucinated file-reference detection
582
251
  - open-loop injection
583
- - cross-compaction delta injection
584
- - post-compaction damage detection
252
+ - project fingerprinting and delta tracking
585
253
  - backup creation before compaction
586
- - metrics logging for LLM cost/latency/cache usage
254
+ - metrics logging and damage detection
587
255
 
588
256
  ---
589
257
 
590
- ## Current caveats
258
+ ## Runtime artifacts
591
259
 
592
- To keep this README aligned with the repository's **actual** current state:
260
+ At runtime, the extension writes to paths under `~/.pi/agent/`, including:
593
261
 
594
- 1. **One legacy test filename remains:** `test/semantic-compact.test.ts`.
595
- 2. **The package is published from `dist/`**, not directly from `src/`. Source and tests are not included in the package tarball.
596
- 3. **The extension depends on Pi runtime APIs and peer packages** (`@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`, `typebox`).
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
- ## Development
601
-
602
- ### Install
272
+ ## Repository layout
603
273
 
604
- ```bash
605
- bun install
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
- ### Test
609
-
610
- ```bash
611
- bun test
612
- bun test test/eval.test.ts
613
- ```
288
+ ---
614
289
 
615
- ### Build
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
- At the moment, this command passes cleanly.
299
+ Build output is published from `dist/`.
634
300
 
635
- ### Typical local path inside Pi
301
+ ---
636
302
 
637
- ```text
638
- ~/.pi/agent/extensions/pi-smart-compact
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
 
@@ -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.1";
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.1";
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.2",
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' && bunx tsc --emitDeclarationOnly --outDir dist",
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": "bunx tsc --noEmit"
45
+ "typecheck": "bun x tsc --noEmit"
46
46
  },
47
47
  "pi": {
48
48
  "extensions": ["./dist/index.js"]