pi-context-kit 0.2.1 → 0.3.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/README.md +48 -53
- package/extensions/index.ts +234 -155
- package/package.json +30 -11
- package/src/config.ts +0 -9
- package/src/context.ts +0 -15
- package/src/maintain.ts +10 -13
- package/src/prune.ts +24 -26
- package/src/shake.ts +20 -11
- package/src/stale.ts +39 -44
- package/src/tool-calls.ts +22 -1
- package/CHANGELOG.md +0 -31
package/README.md
CHANGED
|
@@ -1,7 +1,25 @@
|
|
|
1
1
|
# pi-context-kit
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
Pi compaction and context management for the [Pi coding agent](https://github.com/earendil-works/pi). It keeps the context of long Pi sessions small: pi-context-kit removes old file copies and old tool outputs from the model's context, and prepares the summary before Pi needs it. The session keeps the original text, and the model can read it again with `recall`.
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
pi install npm:pi-context-kit
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
Restart Pi after the install. The defaults work without configuration. Requirements: Pi 1.0.3 or later, Node.js 22.19 or later.
|
|
10
|
+
|
|
11
|
+
## Pi alone, and Pi with pi-context-kit
|
|
12
|
+
|
|
13
|
+
| In a long session | Pi alone | With pi-context-kit |
|
|
14
|
+
| --- | --- | --- |
|
|
15
|
+
| The model reads the same file again | Both copies stay in the context. | The old copy is replaced, above the threshold. |
|
|
16
|
+
| Old tool outputs fill the context | They stay until Pi summarizes. | They are replaced with a short notice. No model request. |
|
|
17
|
+
| The context reaches the limit | Pi writes a summary. | A handoff note can be ready, because it was written in the background. |
|
|
18
|
+
| The model needs a removed detail | The summary is all that remains in the context. | The model calls `recall` to read the original text. |
|
|
19
|
+
|
|
20
|
+
The original session entries never change. Only the context that Pi sends to the model becomes smaller.
|
|
21
|
+
|
|
22
|
+
This extension is for Pi users with long sessions: many file reads, long command outputs, or many compactions. In a short session, the context rarely reaches the threshold. Then the context does not change at the end of a turn. A background handoff note can still start near the threshold, and `/compact` uses a handoff note instead of Pi's summary.
|
|
5
23
|
|
|
6
24
|
## The problem
|
|
7
25
|
|
|
@@ -14,9 +32,9 @@ A summary can lose details, and it costs time and money.
|
|
|
14
32
|
|
|
15
33
|
pi-context-kit does three things:
|
|
16
34
|
|
|
17
|
-
1. It
|
|
18
|
-
2. When a summary is necessary, it
|
|
19
|
-
3. It
|
|
35
|
+
1. It replaces repeated file reads and old tool outputs in the model's context.
|
|
36
|
+
2. When a summary is necessary, it can prepare a handoff note in advance.
|
|
37
|
+
3. It leaves the original session entries unchanged. The model can retrieve earlier text on the current branch with `recall`.
|
|
20
38
|
|
|
21
39
|
## Words used in this document
|
|
22
40
|
|
|
@@ -45,6 +63,8 @@ pi-context-kit does three things:
|
|
|
45
63
|
|
|
46
64
|
To check the installation, type `pi list`. The list must show `npm:pi-context-kit`.
|
|
47
65
|
|
|
66
|
+
To update, type `pi update npm:pi-context-kit` and restart Pi.
|
|
67
|
+
|
|
48
68
|
To remove it, type `pi remove npm:pi-context-kit` and restart Pi.
|
|
49
69
|
|
|
50
70
|
## Recommended setup
|
|
@@ -102,7 +122,7 @@ Sometimes the model reads the same file two times. The first copy is then old.
|
|
|
102
122
|
pi-context-kit replaces the old copy with this text: `[Superseded by a newer read of this file]`.
|
|
103
123
|
|
|
104
124
|
It does this only when the newer read covers all of the old read. If the newer read was cut short, the old copy stays.
|
|
105
|
-
It does this only
|
|
125
|
+
It does this only when the context is above the threshold, in the same change as pruning, shaking or compaction. Each change to old text makes the provider read all later text again without its cache. With Anthropic, it also removes the model's earlier reasoning from the request. One change near the threshold costs less than one change at each turn.
|
|
106
126
|
|
|
107
127
|
### 2. A handoff note is prepared in advance
|
|
108
128
|
|
|
@@ -132,18 +152,25 @@ Your work continues during these steps. pi-context-kit never stops a running tas
|
|
|
132
152
|
|
|
133
153
|
### The `recall` tool
|
|
134
154
|
|
|
135
|
-
The
|
|
155
|
+
The `recall` tool reads original session text, not the shortened context sent to the model. It can:
|
|
156
|
+
|
|
157
|
+
- search earlier conversation text on the current branch, including removed and summarized messages;
|
|
158
|
+
- read an entry's text by ID, with pagination for large entries.
|
|
159
|
+
|
|
160
|
+
Other branches and sessions are excluded. System prompt entries are not searched.
|
|
161
|
+
Images remain in the original session entries, but `recall` returns only their MIME types, not image content.
|
|
162
|
+
The model must call `recall` to retrieve a missing detail. Retrieval is not automatic.
|
|
136
163
|
|
|
137
|
-
|
|
138
|
-
- read one full entry, with the ID given in a notice.
|
|
164
|
+
## What maintenance preserves
|
|
139
165
|
|
|
140
|
-
|
|
166
|
+
File-read replacement, pruning, and shaking do not rewrite the original session entries.
|
|
167
|
+
In the model's context, these steps preserve:
|
|
141
168
|
|
|
142
|
-
|
|
169
|
+
- Your messages, including your instructions and images.
|
|
170
|
+
- The model's tool calls and reasoning. Anthropic can still drop the reasoning after an edited message (see [Old file reads are replaced](#1-old-file-reads-are-replaced)).
|
|
171
|
+
- Tool-call and tool-result pairs. Each tool call keeps its result, but the result content can be shortened.
|
|
143
172
|
|
|
144
|
-
|
|
145
|
-
- The tool calls of the model, and the model's reasoning.
|
|
146
|
-
- The pairs of tool call and tool result. Each tool call keeps its result.
|
|
173
|
+
Compaction is different: it replaces older context with a summary, including older user messages. The original entries remain in session history.
|
|
147
174
|
|
|
148
175
|
## Settings
|
|
149
176
|
|
|
@@ -175,7 +202,6 @@ Copy only the lines that you want to change.
|
|
|
175
202
|
"methodOrder": ["handoff", "shake", "soft"],
|
|
176
203
|
"asyncEnabled": true,
|
|
177
204
|
"supersedeReads": true,
|
|
178
|
-
"staleSuffixTokens": 8000,
|
|
179
205
|
"progressRatio": 0.8,
|
|
180
206
|
"prune": {
|
|
181
207
|
"enabled": true,
|
|
@@ -202,7 +228,6 @@ Copy only the lines that you want to change.
|
|
|
202
228
|
| [`methodOrder`](#methodorder) | A list of `"handoff"`, `"shake"`, `"soft"` | `["handoff", "shake", "soft"]` | The methods to try, and their order. |
|
|
203
229
|
| [`asyncEnabled`](#asyncenabled) | `true`, `false` | `true` | Prepares the handoff note in the background. |
|
|
204
230
|
| [`supersedeReads`](#supersedereads) | `true`, `false` | `true` | Replaces old copies of a file that was read again. |
|
|
205
|
-
| [`staleSuffixTokens`](#stalesuffixtokens) | A whole number, 0 or more | `8000` | Limits which old copies can be replaced. |
|
|
206
231
|
| [`progressRatio`](#progressratio) | A number above 0, up to 1 | `0.8` | How small the context must become. |
|
|
207
232
|
| [`prune.enabled`](#pruneenabled) | `true`, `false` | `true` | Turns pruning of old tool outputs on or off. |
|
|
208
233
|
| [`prune.protectTokens`](#pruneprotecttokens) | A whole number, 0 or more | `40000` | The newest tool outputs that are never pruned. |
|
|
@@ -325,7 +350,7 @@ Example: try shaking first, because it does not call the model.
|
|
|
325
350
|
|
|
326
351
|
Prepares the handoff note in the background, before the threshold.
|
|
327
352
|
|
|
328
|
-
- `true` (default): the note starts one eighth of the threshold early, with a maximum of 32,000 tokens.
|
|
353
|
+
- `true` (default): the note starts one eighth of the threshold early, with a maximum of 32,000 tokens. If the note is ready at the threshold, compaction is fast.
|
|
329
354
|
- `false`: no background note. At the threshold, pi-context-kit writes a new note. Your work waits for this note.
|
|
330
355
|
|
|
331
356
|
This setting has an effect only if `"handoff"` is in `methodOrder` before `"soft"`.
|
|
@@ -343,27 +368,12 @@ Replaces the old copy of a file when the model reads the same file again.
|
|
|
343
368
|
- `true` (default): the old copy becomes `[Superseded by a newer read of this file]`.
|
|
344
369
|
- `false`: all copies stay.
|
|
345
370
|
|
|
346
|
-
This works
|
|
371
|
+
This works only above the threshold, together with pruning and shaking.
|
|
347
372
|
|
|
348
373
|
```json
|
|
349
374
|
{ "contextKit": { "supersedeReads": false } }
|
|
350
375
|
```
|
|
351
376
|
|
|
352
|
-
### `staleSuffixTokens`
|
|
353
|
-
|
|
354
|
-
Limits which old file copies `supersedeReads` can replace.
|
|
355
|
-
pi-context-kit replaces an old copy only if the old copy and all newer text are smaller than this number of tokens. Thus only recent copies are replaced.
|
|
356
|
-
|
|
357
|
-
Why: the provider can keep the start of the conversation in a cache. A change in old text can make the provider read all the text after it again, which costs more.
|
|
358
|
-
|
|
359
|
-
- `8000` (default).
|
|
360
|
-
- A larger value replaces more copies, but can cause more cache misses.
|
|
361
|
-
- `0` replaces nothing. It has the same effect as `"supersedeReads": false`.
|
|
362
|
-
|
|
363
|
-
```json
|
|
364
|
-
{ "contextKit": { "staleSuffixTokens": 16000 } }
|
|
365
|
-
```
|
|
366
|
-
|
|
367
377
|
### `progressRatio`
|
|
368
378
|
|
|
369
379
|
How small the context must become after a method, as a fraction of the threshold.
|
|
@@ -459,7 +469,7 @@ These settings belong to Pi, not to pi-context-kit. Put them in the `compaction`
|
|
|
459
469
|
|
|
460
470
|
| Pi setting | Default | Effect on pi-context-kit |
|
|
461
471
|
| --- | --- | --- |
|
|
462
|
-
| `compaction.enabled` | `true` | `false` stops Pi's compaction. Then pi-context-kit only
|
|
472
|
+
| `compaction.enabled` | `true` | `false` stops Pi's automatic compaction. Then pi-context-kit changes the context only on `/compact`, because there is no threshold. |
|
|
463
473
|
| `compaction.reserveTokens` | `16384` | Pi's limit is the context window minus this number. pi-context-kit always starts at this limit or before. |
|
|
464
474
|
| `compaction.keepRecentTokens` | `20000` | After a handoff note, approximately this number of the newest tokens stays unchanged. |
|
|
465
475
|
| `compaction.modelOverrides` | none | Changes `reserveTokens` and `keepRecentTokens` for one model. |
|
|
@@ -515,7 +525,7 @@ To combine recipes, put all the settings in one `contextKit` block:
|
|
|
515
525
|
- **Pi still has its own limit.** Pi compacts when the context reaches the context window minus `compaction.reserveTokens` (default 16,384). pi-context-kit can only start earlier, not later. You set Pi's limit with `compaction.reserveTokens` and `compaction.modelOverrides`.
|
|
516
526
|
- **A threshold is not a guarantee.** At the threshold, pi-context-kit tries to make the context smaller. If one tool output is very large, or the summary request fails, the methods can fail. Then Pi compacts at its own limit.
|
|
517
527
|
- **Token counts are estimates.** pi-context-kit uses Pi's estimates. The real count of the provider can be different.
|
|
518
|
-
- **If Pi's compaction is off** (`compaction.enabled: false`), pi-context-kit only
|
|
528
|
+
- **If Pi's compaction is off** (`compaction.enabled: false`), pi-context-kit changes the context only when you run `/compact`. Then it writes a handoff note, as with compaction on. `thresholdTokens` and `thresholdPercent` are ignored, because pi-context-kit edits the context automatically only at a threshold.
|
|
519
529
|
- **Manual compaction and errors.** When you type `/compact`, when the context is too large for the model, or when Pi compacts before a turn, `shake` cannot run. pi-context-kit uses a ready handoff note, or Pi's summary.
|
|
520
530
|
- **`methodOrder` stops at `soft`.** The methods after `soft` do not run.
|
|
521
531
|
- **Subagents** use their own settings. They show no warnings, because they have no screen.
|
|
@@ -546,27 +556,12 @@ npm run check
|
|
|
546
556
|
```
|
|
547
557
|
|
|
548
558
|
The tests run offline with Pi's faux provider. They do not call a real model.
|
|
559
|
+
Development uses Pi `1.5.2`. The oldest supported version is Pi `1.0.3`. CI checks the locked dependencies on Node 22 and 24, and Pi `1.0.3` and latest Pi on Node 24.
|
|
560
|
+
Host-provided peer dependencies use `"*"`, as required by Pi's package guide. This is not a guarantee that every Pi version works.
|
|
549
561
|
|
|
550
562
|
## Contributing and releases
|
|
551
563
|
|
|
552
|
-
See [CONTRIBUTING.md](CONTRIBUTING.md) for local checks
|
|
553
|
-
|
|
554
|
-
1. Open a pull request. CI runs `npm run check` on Node 22 and 24.
|
|
555
|
-
2. Add user-visible changes under `## Unreleased` in `CHANGELOG.md`.
|
|
556
|
-
3. Choose `patch` for fixes, `minor` for compatible features, or `major` for breaking changes.
|
|
557
|
-
4. Run `npm run release -- <patch|minor|major|x.y.z>` from an up-to-date, clean `main`. This opens a release PR with matching package and lockfile versions, versioned notes, and an empty `Unreleased` section.
|
|
558
|
-
5. Merge the release PR, then wait for CI to succeed on the exact `main` commit you want to publish.
|
|
559
|
-
6. Create `vX.Y.Z` at that commit and push that tag. The tag must match the package version. Release tags cannot be moved or deleted.
|
|
560
|
-
7. As the repository owner, launch **Publish release** at that tag: `gh workflow run release.yml --ref vX.Y.Z -f tag=vX.Y.Z`.
|
|
561
|
-
8. Approve the `npm` environment deployment. The owner can approve their own run; no third-party approval is needed.
|
|
562
|
-
|
|
563
|
-
Merges, pushes, and tag creation never publish. The manual workflow requires an existing stable-version tag, matching manifests and release notes, and successful CI on its exact commit. That commit must belong to `main`. The dispatch ref and input tag must match. Running from the tag keeps npm provenance tied to the selected commit.
|
|
564
|
-
|
|
565
|
-
The workflow tests and publishes that commit, not the current tip of `main`, then creates the GitHub release. A new npm publication updates the `latest` dist-tag.
|
|
566
|
-
|
|
567
|
-
If publication fails, fix the cause and use **Re-run failed jobs** on the original run, with the same tag. An existing npm version must have the same source commit; mismatches fail instead of overwriting a release. For code changes, prepare a new version and tag. npm can take time to make an accepted publication visible.
|
|
568
|
-
|
|
569
|
-
The workflow uses npm trusted publishing, so the repository stores no npm token. Configure the npm trusted publisher for this repository, `release.yml`, and the GitHub environment `npm`. Restrict that environment to tags `v*`, with the owner as its required reviewer and self-review allowed. The workflow checks that the tagged commit belongs to `main`. Protect `v*` tags from updates and deletion, with no bypass actors. Keep these repository protections enabled to preserve release identity across retries.
|
|
564
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) for local checks, pull requests and releases. Report vulnerabilities through [SECURITY.md](SECURITY.md), not public issues.
|
|
570
565
|
|
|
571
566
|
## License
|
|
572
567
|
|
package/extensions/index.ts
CHANGED
|
@@ -1,16 +1,15 @@
|
|
|
1
|
-
import {
|
|
2
|
-
|
|
3
|
-
type Message,
|
|
4
|
-
type Model,
|
|
5
|
-
Type,
|
|
6
|
-
} from "@earendil-works/pi-ai";
|
|
1
|
+
import { type Api, type Message, type Model } from "@earendil-works/pi-ai";
|
|
2
|
+
import { Type } from "typebox";
|
|
7
3
|
import {
|
|
8
4
|
convertToLlm,
|
|
5
|
+
type CompactionEntryDraft,
|
|
9
6
|
type ExtensionAPI,
|
|
10
7
|
type ExtensionContext,
|
|
11
8
|
findCutPoint,
|
|
12
9
|
generateSummaryWithUsage,
|
|
13
10
|
getLatestCompactionEntry,
|
|
11
|
+
type ProjectedSessionEntry,
|
|
12
|
+
type SessionBeforeCompactEvent,
|
|
14
13
|
type SessionEntry,
|
|
15
14
|
SettingsManager,
|
|
16
15
|
} from "@earendil-works/pi-coding-agent";
|
|
@@ -35,7 +34,7 @@ import {
|
|
|
35
34
|
toDrafts,
|
|
36
35
|
} from "../src/context.ts";
|
|
37
36
|
import { handoffSummary } from "../src/handoff.ts";
|
|
38
|
-
import { planMaintenance } from "../src/maintain.ts";
|
|
37
|
+
import { type MaintenancePlan, planMaintenance } from "../src/maintain.ts";
|
|
39
38
|
import { requestNote } from "../src/note.ts";
|
|
40
39
|
import { readEntry, searchEntries } from "../src/recall.ts";
|
|
41
40
|
|
|
@@ -220,18 +219,128 @@ export default function contextKit(pi: ExtensionAPI): void {
|
|
|
220
219
|
: undefined;
|
|
221
220
|
};
|
|
222
221
|
|
|
222
|
+
/** Starts a background note shortly before the threshold, so compaction need not wait for one. */
|
|
223
|
+
const speculate = (
|
|
224
|
+
turn: Turn,
|
|
225
|
+
leafId: string,
|
|
226
|
+
keptEntryId: string | undefined,
|
|
227
|
+
messages: () => Message[],
|
|
228
|
+
) => {
|
|
229
|
+
const { ctx, config, model, limit, result } = turn;
|
|
230
|
+
if (!config.asyncEnabled || !keptEntryId) return;
|
|
231
|
+
if (result.tokens <= limit - speculationLead(limit)) return;
|
|
232
|
+
if (result.tokens > limit) return;
|
|
233
|
+
const budget = Math.floor(
|
|
234
|
+
limit * config.progressRatio - keptTokens(ctx, keptEntryId),
|
|
235
|
+
);
|
|
236
|
+
if (budget <= 0) return;
|
|
237
|
+
const context = messages();
|
|
238
|
+
const maxTokens = Math.min(model.maxTokens, budget);
|
|
239
|
+
background.start(
|
|
240
|
+
turn.current,
|
|
241
|
+
leafId,
|
|
242
|
+
(signal) =>
|
|
243
|
+
requestNote({
|
|
244
|
+
registry: ctx.modelRegistry,
|
|
245
|
+
model,
|
|
246
|
+
sessionId: ctx.sessionManager.getSessionId(),
|
|
247
|
+
messages: context,
|
|
248
|
+
reasoning: reasoning(),
|
|
249
|
+
signal,
|
|
250
|
+
maxTokens,
|
|
251
|
+
}),
|
|
252
|
+
(error) => warn(ctx, error, "A new note is written at compaction."),
|
|
253
|
+
);
|
|
254
|
+
};
|
|
255
|
+
|
|
256
|
+
/** `"waiting"` means a background note is still being written for this threshold. */
|
|
257
|
+
const handoffAtTurn = async (turn: Turn) => {
|
|
258
|
+
const { ctx, model, limit, current, result } = turn;
|
|
259
|
+
const leafId = ctx.sessionManager.getLeafId();
|
|
260
|
+
if (!leafId) return undefined;
|
|
261
|
+
const messages = () =>
|
|
262
|
+
convertToLlm(projectedMessages(applyEdits(turn.entries, result.edits)));
|
|
263
|
+
const recent = recentStart(ctx, compactionSettings(model).keepRecentTokens);
|
|
264
|
+
speculate(turn, leafId, recent, messages);
|
|
265
|
+
if (result.tokens <= limit || !recent || failedEpoch === current)
|
|
266
|
+
return undefined;
|
|
267
|
+
const writing = background.writing(current);
|
|
268
|
+
if (writing && limit < piThreshold(model)) return "waiting" as const;
|
|
269
|
+
return tryHandoff(turn, recent, writing ? undefined : messages);
|
|
270
|
+
};
|
|
271
|
+
|
|
272
|
+
const tryHandoff = async (
|
|
273
|
+
turn: Turn,
|
|
274
|
+
keptEntryId: string,
|
|
275
|
+
messages: (() => Message[]) | undefined,
|
|
276
|
+
) => {
|
|
277
|
+
const { ctx, current } = turn;
|
|
278
|
+
const signal = ctx.signal ?? new AbortController().signal;
|
|
279
|
+
try {
|
|
280
|
+
const compaction = await handoff({
|
|
281
|
+
ctx,
|
|
282
|
+
model: turn.model,
|
|
283
|
+
config: turn.config,
|
|
284
|
+
branch: turn.branch,
|
|
285
|
+
ready: await background.takeReady(current, turn.branch),
|
|
286
|
+
keptEntryId,
|
|
287
|
+
limit: turn.limit,
|
|
288
|
+
messages: messages?.(),
|
|
289
|
+
signal,
|
|
290
|
+
cancelBackground: () => background.cancel(),
|
|
291
|
+
});
|
|
292
|
+
if (compaction) {
|
|
293
|
+
background.cancel();
|
|
294
|
+
return compacted(turn.result, compaction);
|
|
295
|
+
}
|
|
296
|
+
} catch (error) {
|
|
297
|
+
if (!signal.aborted)
|
|
298
|
+
warn(ctx, error, "The remaining methods in methodOrder are tried.");
|
|
299
|
+
}
|
|
300
|
+
failedEpoch = current;
|
|
301
|
+
return undefined;
|
|
302
|
+
};
|
|
303
|
+
|
|
304
|
+
const softAtTurn = async (turn: Turn) => {
|
|
305
|
+
const { ctx, model, limit, current, result } = turn;
|
|
306
|
+
const due =
|
|
307
|
+
result.tokens > limit &&
|
|
308
|
+
limit < piThreshold(model) &&
|
|
309
|
+
turn.config.methodOrder.includes("soft") &&
|
|
310
|
+
softFailedEpoch !== current;
|
|
311
|
+
if (!due) return undefined;
|
|
312
|
+
try {
|
|
313
|
+
const compaction = await soft({
|
|
314
|
+
ctx,
|
|
315
|
+
model,
|
|
316
|
+
config: turn.config,
|
|
317
|
+
branch: turn.branch,
|
|
318
|
+
entries: applyEdits(turn.entries, result.edits),
|
|
319
|
+
limit,
|
|
320
|
+
});
|
|
321
|
+
if (compaction) return compacted(result, compaction);
|
|
322
|
+
} catch (error) {
|
|
323
|
+
if (!ctx.signal?.aborted)
|
|
324
|
+
warn(ctx, error, "Pi compacts at its own threshold.", "Pi's summary");
|
|
325
|
+
}
|
|
326
|
+
softFailedEpoch = current;
|
|
327
|
+
return undefined;
|
|
328
|
+
};
|
|
329
|
+
|
|
223
330
|
pi.on("turn_end", async (event, ctx) => {
|
|
224
331
|
const config = settings(ctx);
|
|
225
332
|
if (!config.enabled) return undefined;
|
|
333
|
+
const branch = ctx.sessionManager.getBranch();
|
|
334
|
+
const current = epoch(branch);
|
|
335
|
+
background.invalidate(current, branch);
|
|
226
336
|
const model = ctx.model;
|
|
337
|
+
// Without a model the threshold is infinite, so maintenance plans no edits.
|
|
338
|
+
if (!model) return undefined;
|
|
227
339
|
const limit = threshold(model, config);
|
|
228
340
|
const methods = config.methodOrder;
|
|
229
341
|
const entries = event.context.contextEntries;
|
|
230
|
-
const
|
|
342
|
+
const tokens = currentTokens(ctx, entries);
|
|
231
343
|
const edited = editedEntryIds(branch);
|
|
232
|
-
const tokens =
|
|
233
|
-
ctx.getContextUsage()?.tokens ??
|
|
234
|
-
contextTokens(projectedMessages(entries));
|
|
235
344
|
const plan = (shake: boolean) =>
|
|
236
345
|
planMaintenance({
|
|
237
346
|
entries,
|
|
@@ -241,161 +350,86 @@ export default function contextKit(pi: ExtensionAPI): void {
|
|
|
241
350
|
threshold: limit,
|
|
242
351
|
});
|
|
243
352
|
const shakeFirst = before(methods, "shake", "handoff");
|
|
244
|
-
|
|
245
|
-
|
|
353
|
+
const turn: Turn = {
|
|
354
|
+
ctx,
|
|
355
|
+
config,
|
|
356
|
+
model,
|
|
357
|
+
limit,
|
|
358
|
+
entries,
|
|
359
|
+
branch,
|
|
360
|
+
current,
|
|
361
|
+
result: plan(shakeFirst),
|
|
362
|
+
};
|
|
246
363
|
|
|
247
|
-
const leafId = ctx.sessionManager.getLeafId();
|
|
248
|
-
const current = epoch(branch);
|
|
249
|
-
background.invalidate(current, branch);
|
|
250
364
|
// Try ordered strategies at Pi's threshold before its native hook can compact.
|
|
251
|
-
const
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
if (
|
|
264
|
-
config.asyncEnabled &&
|
|
265
|
-
speculativeBudget > 0 &&
|
|
266
|
-
result.tokens > limit - speculationLead(limit) &&
|
|
267
|
-
result.tokens <= limit
|
|
268
|
-
) {
|
|
269
|
-
const context = messages();
|
|
270
|
-
const maxTokens = Math.min(model.maxTokens, speculativeBudget);
|
|
271
|
-
background.start(
|
|
272
|
-
current,
|
|
273
|
-
leafId,
|
|
274
|
-
(signal) =>
|
|
275
|
-
requestNote({
|
|
276
|
-
registry: ctx.modelRegistry,
|
|
277
|
-
model,
|
|
278
|
-
sessionId: ctx.sessionManager.getSessionId(),
|
|
279
|
-
messages: context,
|
|
280
|
-
reasoning: reasoning(),
|
|
281
|
-
signal,
|
|
282
|
-
maxTokens,
|
|
283
|
-
}),
|
|
284
|
-
(error) => warn(ctx, error, "A new note is written at compaction."),
|
|
285
|
-
);
|
|
286
|
-
}
|
|
287
|
-
if (own && keptEntryId && failedEpoch !== current) {
|
|
288
|
-
const writing = background.writing(current);
|
|
289
|
-
if (writing && limit < piThreshold(model)) return { entries: drafts() };
|
|
290
|
-
const signal = ctx.signal ?? new AbortController().signal;
|
|
291
|
-
try {
|
|
292
|
-
const compaction = await handoff({
|
|
293
|
-
ctx,
|
|
294
|
-
model,
|
|
295
|
-
config,
|
|
296
|
-
branch,
|
|
297
|
-
ready: await background.takeReady(current, branch),
|
|
298
|
-
keptEntryId,
|
|
299
|
-
limit,
|
|
300
|
-
messages: writing ? undefined : messages(),
|
|
301
|
-
signal,
|
|
302
|
-
cancelBackground: () => background.cancel(),
|
|
303
|
-
});
|
|
304
|
-
if (compaction) {
|
|
305
|
-
background.cancel();
|
|
306
|
-
return {
|
|
307
|
-
entries: [...drafts(), { type: "compaction", ...compaction }],
|
|
308
|
-
};
|
|
309
|
-
}
|
|
310
|
-
failedEpoch = current;
|
|
311
|
-
} catch (error) {
|
|
312
|
-
failedEpoch = current;
|
|
313
|
-
if (!signal.aborted)
|
|
314
|
-
warn(ctx, error, "The remaining methods in methodOrder are tried.");
|
|
315
|
-
}
|
|
316
|
-
}
|
|
317
|
-
}
|
|
318
|
-
const shakeAfterHandoff = !shakeFirst && before(methods, "shake", "soft");
|
|
319
|
-
if (tokens > limit && shakeAfterHandoff) result = plan(true);
|
|
320
|
-
const softDue =
|
|
321
|
-
model &&
|
|
322
|
-
result.tokens > limit &&
|
|
323
|
-
limit < piThreshold(model) &&
|
|
324
|
-
methods.includes("soft") &&
|
|
325
|
-
softFailedEpoch !== current;
|
|
326
|
-
if (softDue) {
|
|
327
|
-
try {
|
|
328
|
-
const compaction = await soft({
|
|
329
|
-
ctx,
|
|
330
|
-
model,
|
|
331
|
-
config,
|
|
332
|
-
branch,
|
|
333
|
-
entries: applyEdits(entries, result.edits),
|
|
334
|
-
limit,
|
|
335
|
-
});
|
|
336
|
-
if (compaction)
|
|
337
|
-
return {
|
|
338
|
-
entries: [...drafts(), { type: "compaction", ...compaction }],
|
|
339
|
-
};
|
|
340
|
-
} catch (error) {
|
|
341
|
-
if (!ctx.signal?.aborted)
|
|
342
|
-
warn(ctx, error, "Pi compacts at its own threshold.", "Pi's summary");
|
|
343
|
-
}
|
|
344
|
-
softFailedEpoch = current;
|
|
345
|
-
}
|
|
346
|
-
return result.edits.length > 0 ? { entries: drafts() } : undefined;
|
|
365
|
+
const handed = before(methods, "handoff", "soft")
|
|
366
|
+
? await handoffAtTurn(turn)
|
|
367
|
+
: undefined;
|
|
368
|
+
if (handed === "waiting") return persisted(turn.result, limit);
|
|
369
|
+
if (handed) return handed;
|
|
370
|
+
if (
|
|
371
|
+
turn.result.tokens > limit &&
|
|
372
|
+
!shakeFirst &&
|
|
373
|
+
before(methods, "shake", "soft")
|
|
374
|
+
)
|
|
375
|
+
turn.result = plan(true);
|
|
376
|
+
return (await softAtTurn(turn)) ?? persisted(turn.result, limit);
|
|
347
377
|
});
|
|
348
378
|
|
|
379
|
+
const handoffBeforeCompact = async (
|
|
380
|
+
event: SessionBeforeCompactEvent,
|
|
381
|
+
ctx: ExtensionContext,
|
|
382
|
+
model: Model<Api>,
|
|
383
|
+
config: ContextKitConfig,
|
|
384
|
+
) => {
|
|
385
|
+
const { preparation, branchEntries, customInstructions } = event;
|
|
386
|
+
const current = epoch(branchEntries);
|
|
387
|
+
background.invalidate(current, branchEntries);
|
|
388
|
+
const writing = !customInstructions && background.writing(current);
|
|
389
|
+
const compaction = await handoff({
|
|
390
|
+
ctx,
|
|
391
|
+
model,
|
|
392
|
+
config,
|
|
393
|
+
branch: branchEntries,
|
|
394
|
+
// A focused /compact needs a note written for that focus.
|
|
395
|
+
ready: customInstructions
|
|
396
|
+
? undefined
|
|
397
|
+
: await background.takeReady(current, branchEntries),
|
|
398
|
+
keptEntryId: preparation.firstKeptEntryId,
|
|
399
|
+
limit: Math.min(threshold(model, config), model.contextWindow),
|
|
400
|
+
// The live context no longer fits the model after an overflow.
|
|
401
|
+
messages:
|
|
402
|
+
event.reason === "overflow" || writing ? undefined : liveMessages(ctx),
|
|
403
|
+
focus: customInstructions,
|
|
404
|
+
signal: event.signal,
|
|
405
|
+
cancelBackground: () => background.cancel(),
|
|
406
|
+
});
|
|
407
|
+
return (
|
|
408
|
+
compaction && {
|
|
409
|
+
compaction: { ...compaction, tokensBefore: preparation.tokensBefore },
|
|
410
|
+
}
|
|
411
|
+
);
|
|
412
|
+
};
|
|
413
|
+
|
|
349
414
|
pi.on("session_before_compact", async (event, ctx) => {
|
|
350
415
|
const model = ctx.model;
|
|
351
416
|
const config = settings(ctx);
|
|
352
|
-
if (
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
!before(config.methodOrder, "handoff", "soft")
|
|
356
|
-
)
|
|
357
|
-
return undefined;
|
|
358
|
-
const { preparation, branchEntries, signal } = event;
|
|
359
|
-
const currentEpoch = epoch(branchEntries);
|
|
360
|
-
if (event.reason === "threshold" && failedEpoch === currentEpoch)
|
|
361
|
-
return undefined;
|
|
362
|
-
const limit = Math.min(threshold(model, config), model.contextWindow);
|
|
417
|
+
if (!model || !handoffEnabled(config)) return undefined;
|
|
418
|
+
const failed = failedEpoch === epoch(event.branchEntries);
|
|
419
|
+
if (event.reason === "threshold" && failed) return undefined;
|
|
363
420
|
try {
|
|
364
|
-
|
|
365
|
-
background.invalidate(current, branchEntries);
|
|
366
|
-
if (event.customInstructions) background.cancel();
|
|
367
|
-
const writing = !event.customInstructions && background.writing(current);
|
|
368
|
-
const compaction = await handoff({
|
|
369
|
-
ctx,
|
|
370
|
-
model,
|
|
371
|
-
config,
|
|
372
|
-
branch: branchEntries,
|
|
373
|
-
// A focused /compact needs a note written for that focus.
|
|
374
|
-
ready: event.customInstructions
|
|
375
|
-
? undefined
|
|
376
|
-
: await background.takeReady(current, branchEntries),
|
|
377
|
-
keptEntryId: preparation.firstKeptEntryId,
|
|
378
|
-
limit,
|
|
379
|
-
// The live context no longer fits the model after an overflow.
|
|
380
|
-
messages:
|
|
381
|
-
event.reason === "overflow" || writing
|
|
382
|
-
? undefined
|
|
383
|
-
: liveMessages(ctx),
|
|
384
|
-
focus: event.customInstructions,
|
|
385
|
-
signal,
|
|
386
|
-
cancelBackground: () => background.cancel(),
|
|
387
|
-
});
|
|
388
|
-
return (
|
|
389
|
-
compaction && {
|
|
390
|
-
compaction: { ...compaction, tokensBefore: preparation.tokensBefore },
|
|
391
|
-
}
|
|
392
|
-
);
|
|
421
|
+
return await handoffBeforeCompact(event, ctx, model, config);
|
|
393
422
|
} catch (error) {
|
|
394
|
-
if (!signal.aborted)
|
|
423
|
+
if (!event.signal.aborted)
|
|
424
|
+
warn(ctx, error, "Pi's summary is used instead.");
|
|
395
425
|
return undefined;
|
|
396
426
|
}
|
|
397
427
|
});
|
|
398
428
|
|
|
429
|
+
pi.on("session_tree", (_event, ctx) => {
|
|
430
|
+
const branch = ctx.sessionManager.getBranch();
|
|
431
|
+
background.invalidate(epoch(branch), branch);
|
|
432
|
+
});
|
|
399
433
|
pi.on("session_compact", () => background.cancel());
|
|
400
434
|
pi.on("session_shutdown", () => background.cancel());
|
|
401
435
|
|
|
@@ -403,8 +437,9 @@ export default function contextKit(pi: ExtensionAPI): void {
|
|
|
403
437
|
name: "recall",
|
|
404
438
|
label: "Recall",
|
|
405
439
|
description:
|
|
406
|
-
"Search or read the
|
|
407
|
-
"
|
|
440
|
+
"Search or read earlier text on the current session branch, including messages removed by compaction and tool outputs that were pruned or elided. " +
|
|
441
|
+
"Other branches are excluded. Images are represented only by MIME type. " +
|
|
442
|
+
"Pass `query` to list matching entries with their IDs, newest first. Pass `entryId` to read one entry's text, with pagination for large entries.",
|
|
408
443
|
parameters: Type.Object({
|
|
409
444
|
query: Type.Optional(
|
|
410
445
|
Type.String({ description: "Text to find, case-insensitive." }),
|
|
@@ -443,6 +478,50 @@ export default function contextKit(pi: ExtensionAPI): void {
|
|
|
443
478
|
});
|
|
444
479
|
}
|
|
445
480
|
|
|
481
|
+
/** One turn boundary's inputs and its current maintenance plan. */
|
|
482
|
+
interface Turn {
|
|
483
|
+
ctx: ExtensionContext;
|
|
484
|
+
config: ContextKitConfig;
|
|
485
|
+
model: Model<Api>;
|
|
486
|
+
limit: number;
|
|
487
|
+
entries: ProjectedSessionEntry[];
|
|
488
|
+
branch: SessionEntry[];
|
|
489
|
+
current: string | null;
|
|
490
|
+
result: MaintenancePlan;
|
|
491
|
+
}
|
|
492
|
+
|
|
493
|
+
// Without compaction, edits that leave the context above the threshold break the cache again next turn.
|
|
494
|
+
function persisted(result: MaintenancePlan, limit: number) {
|
|
495
|
+
return result.edits.length > 0 && result.tokens <= limit
|
|
496
|
+
? { entries: toDrafts(result.edits) }
|
|
497
|
+
: undefined;
|
|
498
|
+
}
|
|
499
|
+
|
|
500
|
+
function compacted(
|
|
501
|
+
result: MaintenancePlan,
|
|
502
|
+
compaction: Omit<CompactionEntryDraft, "type">,
|
|
503
|
+
) {
|
|
504
|
+
return {
|
|
505
|
+
entries: [
|
|
506
|
+
...toDrafts(result.edits),
|
|
507
|
+
{ type: "compaction" as const, ...compaction },
|
|
508
|
+
],
|
|
509
|
+
};
|
|
510
|
+
}
|
|
511
|
+
|
|
512
|
+
function currentTokens(
|
|
513
|
+
ctx: ExtensionContext,
|
|
514
|
+
entries: readonly ProjectedSessionEntry[],
|
|
515
|
+
): number {
|
|
516
|
+
return (
|
|
517
|
+
ctx.getContextUsage()?.tokens ?? contextTokens(projectedMessages(entries))
|
|
518
|
+
);
|
|
519
|
+
}
|
|
520
|
+
|
|
521
|
+
function handoffEnabled(config: ContextKitConfig): boolean {
|
|
522
|
+
return config.enabled && before(config.methodOrder, "handoff", "soft");
|
|
523
|
+
}
|
|
524
|
+
|
|
446
525
|
function liveMessages(ctx: ExtensionContext): Message[] {
|
|
447
526
|
return convertToLlm(ctx.sessionManager.buildSessionProjection().messages);
|
|
448
527
|
}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-context-kit",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.3.1",
|
|
4
|
+
"description": "Pi compaction and context management for the Pi coding agent: replace stale file reads, prune old tool outputs, prepare handoff notes in the background, and recall the original text.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"author": "HugoLopes45 (https://github.com/HugoLopes45)",
|
|
@@ -15,37 +15,56 @@
|
|
|
15
15
|
},
|
|
16
16
|
"keywords": [
|
|
17
17
|
"pi-package",
|
|
18
|
-
"pi-extension",
|
|
19
18
|
"pi",
|
|
19
|
+
"pi-extension",
|
|
20
|
+
"pi-coding-agent",
|
|
20
21
|
"compaction",
|
|
21
22
|
"context",
|
|
22
|
-
"
|
|
23
|
+
"context-window",
|
|
24
|
+
"context-management",
|
|
25
|
+
"coding-agent",
|
|
26
|
+
"llm",
|
|
27
|
+
"handoff",
|
|
28
|
+
"token-optimization"
|
|
23
29
|
],
|
|
24
30
|
"files": [
|
|
25
31
|
"extensions",
|
|
26
|
-
"src"
|
|
27
|
-
"CHANGELOG.md"
|
|
32
|
+
"src"
|
|
28
33
|
],
|
|
34
|
+
"engines": {
|
|
35
|
+
"node": ">=22.19.0"
|
|
36
|
+
},
|
|
29
37
|
"pi": {
|
|
30
38
|
"extensions": [
|
|
31
39
|
"./extensions/index.ts"
|
|
32
40
|
]
|
|
33
41
|
},
|
|
34
42
|
"scripts": {
|
|
35
|
-
"check": "
|
|
43
|
+
"check": "tsc --noEmit && npm run lint && vitest --run",
|
|
44
|
+
"lint": "node scripts/lint.ts",
|
|
36
45
|
"test": "vitest --run",
|
|
37
|
-
"release": "node scripts/release.ts prepare",
|
|
38
46
|
"prepublishOnly": "test -n \"$GITHUB_ACTIONS\" || test \"$(npm whoami)\" = hugolopes45 || { echo 'Publish only as the npm user hugolopes45.' >&2; exit 1; }; npm run check"
|
|
39
47
|
},
|
|
40
48
|
"peerDependencies": {
|
|
41
49
|
"@earendil-works/pi-ai": "*",
|
|
42
|
-
"@earendil-works/pi-coding-agent": "*"
|
|
50
|
+
"@earendil-works/pi-coding-agent": "*",
|
|
51
|
+
"typebox": "*"
|
|
43
52
|
},
|
|
44
53
|
"devDependencies": {
|
|
45
|
-
"@earendil-works/pi-ai": "^1.
|
|
46
|
-
"@earendil-works/pi-coding-agent": "^1.
|
|
54
|
+
"@earendil-works/pi-ai": "^1.5.2",
|
|
55
|
+
"@earendil-works/pi-coding-agent": "^1.5.2",
|
|
47
56
|
"@types/node": "^26.6.4",
|
|
57
|
+
"eslint": "^10.14.0",
|
|
58
|
+
"typebox": "^1.3.27",
|
|
48
59
|
"typescript": "^7.0.2",
|
|
49
60
|
"vitest": "^5.0.3"
|
|
61
|
+
},
|
|
62
|
+
"overrides": {
|
|
63
|
+
"eslint": {
|
|
64
|
+
"minimatch": "^11.0.8"
|
|
65
|
+
},
|
|
66
|
+
"@eslint/config-array": {
|
|
67
|
+
"minimatch": "^11.0.8"
|
|
68
|
+
}
|
|
50
69
|
}
|
|
51
70
|
}
|
package/src/config.ts
CHANGED
|
@@ -12,8 +12,6 @@ export interface ContextKitConfig {
|
|
|
12
12
|
methodOrder: Method[];
|
|
13
13
|
/** Replace older reads of a file that was read again. */
|
|
14
14
|
supersedeReads: boolean;
|
|
15
|
-
/** Superseded reads are replaced only within this many newest tokens, to keep the prompt cache. */
|
|
16
|
-
staleSuffixTokens: number;
|
|
17
15
|
prune: PruneOptions & { enabled: boolean };
|
|
18
16
|
shake: ShakeOptions;
|
|
19
17
|
/** Pruning and shaking must reach this fraction of the threshold, or compaction runs instead. */
|
|
@@ -39,7 +37,6 @@ export const DEFAULT_CONFIG: ContextKitConfig = {
|
|
|
39
37
|
thresholdPercent: -1,
|
|
40
38
|
methodOrder: [...METHODS],
|
|
41
39
|
supersedeReads: true,
|
|
42
|
-
staleSuffixTokens: 8_000,
|
|
43
40
|
prune: {
|
|
44
41
|
enabled: true,
|
|
45
42
|
protectTokens: 40_000,
|
|
@@ -154,11 +151,6 @@ export function readConfig(raw: unknown): ConfigResult {
|
|
|
154
151
|
);
|
|
155
152
|
const methods = root.get("methodOrder", methodOrder, d.methodOrder);
|
|
156
153
|
const supersedeReads = root.get("supersedeReads", boolean, d.supersedeReads);
|
|
157
|
-
const staleSuffixTokens = root.get(
|
|
158
|
-
"staleSuffixTokens",
|
|
159
|
-
count,
|
|
160
|
-
d.staleSuffixTokens,
|
|
161
|
-
);
|
|
162
154
|
const progressRatio = root.get("progressRatio", ratio, d.progressRatio);
|
|
163
155
|
|
|
164
156
|
const p = root.section("prune");
|
|
@@ -188,7 +180,6 @@ export function readConfig(raw: unknown): ConfigResult {
|
|
|
188
180
|
thresholdPercent,
|
|
189
181
|
methodOrder: [...new Set(methods.filter(isMethod))],
|
|
190
182
|
supersedeReads,
|
|
191
|
-
staleSuffixTokens,
|
|
192
183
|
prune,
|
|
193
184
|
shake,
|
|
194
185
|
progressRatio,
|
package/src/context.ts
CHANGED
|
@@ -46,21 +46,6 @@ export function messageTokens(message: AgentMessage): number {
|
|
|
46
46
|
return estimateTokens(message);
|
|
47
47
|
}
|
|
48
48
|
|
|
49
|
-
/** Tokens from each entry through the end of the projected context. */
|
|
50
|
-
export function suffixTokens(
|
|
51
|
-
entries: readonly ProjectedSessionEntry[],
|
|
52
|
-
): number[] {
|
|
53
|
-
const suffix = new Array<number>(entries.length).fill(0);
|
|
54
|
-
let total = 0;
|
|
55
|
-
for (let i = entries.length - 1; i >= 0; i--) {
|
|
56
|
-
for (const message of entries[i]?.messages ?? []) {
|
|
57
|
-
if (message.role !== "system") total += estimateTokens(message);
|
|
58
|
-
}
|
|
59
|
-
suffix[i] = total;
|
|
60
|
-
}
|
|
61
|
-
return suffix;
|
|
62
|
-
}
|
|
63
|
-
|
|
64
49
|
export function withContent(
|
|
65
50
|
message: EditableMessage,
|
|
66
51
|
content: ContextEditableContent,
|
package/src/maintain.ts
CHANGED
|
@@ -12,7 +12,7 @@ import { supersededReads } from "./stale.ts";
|
|
|
12
12
|
|
|
13
13
|
export type MaintenanceOptions = Pick<
|
|
14
14
|
ContextKitConfig,
|
|
15
|
-
"supersedeReads" | "
|
|
15
|
+
"supersedeReads" | "prune" | "progressRatio"
|
|
16
16
|
> & {
|
|
17
17
|
/** Undefined leaves the context unshaken. */
|
|
18
18
|
shake: ShakeOptions | undefined;
|
|
@@ -35,24 +35,19 @@ export interface MaintenancePlan {
|
|
|
35
35
|
}
|
|
36
36
|
|
|
37
37
|
/**
|
|
38
|
-
* Plans context edits for one turn boundary. Any context edit
|
|
39
|
-
*
|
|
40
|
-
*
|
|
38
|
+
* Plans context edits for one turn boundary. Any context edit changes the prompt prefix, so the
|
|
39
|
+
* provider cache and, on Anthropic, the thinking blocks after the edit are lost. Edits are
|
|
40
|
+
* therefore made only above the compaction threshold, in one batch.
|
|
41
41
|
*/
|
|
42
42
|
export function planMaintenance(input: MaintenanceInput): MaintenancePlan {
|
|
43
43
|
const { options } = input;
|
|
44
44
|
const unchanged = { edits: [], tokens: input.tokens };
|
|
45
|
+
if (input.tokens <= input.threshold) return unchanged;
|
|
46
|
+
|
|
45
47
|
const stale = options.supersedeReads
|
|
46
|
-
? supersededReads(input.entries, input.edited
|
|
48
|
+
? supersededReads(input.entries, input.edited)
|
|
47
49
|
: [];
|
|
48
50
|
const afterStale = applyEdits(input.entries, stale);
|
|
49
|
-
const staleTokens = contextTokens(projectedMessages(afterStale));
|
|
50
|
-
|
|
51
|
-
if (input.tokens <= input.threshold) {
|
|
52
|
-
return stale.length > 0 && staleTokens <= input.threshold
|
|
53
|
-
? { edits: stale, tokens: staleTokens }
|
|
54
|
-
: unchanged;
|
|
55
|
-
}
|
|
56
51
|
|
|
57
52
|
const edited = new Set([
|
|
58
53
|
...input.edited,
|
|
@@ -71,7 +66,9 @@ export function planMaintenance(input: MaintenanceInput): MaintenancePlan {
|
|
|
71
66
|
return edits.length > 0 ? { edits, tokens: reducedTokens } : unchanged;
|
|
72
67
|
}
|
|
73
68
|
// Compaction runs next. Stale edits only shrink what it has to summarize.
|
|
74
|
-
return stale.length > 0
|
|
69
|
+
return stale.length > 0
|
|
70
|
+
? { edits: stale, tokens: contextTokens(projectedMessages(afterStale)) }
|
|
71
|
+
: unchanged;
|
|
75
72
|
}
|
|
76
73
|
|
|
77
74
|
function latestPerTarget(edits: readonly Edit[]): Edit[] {
|
package/src/prune.ts
CHANGED
|
@@ -1,11 +1,6 @@
|
|
|
1
1
|
import type { ProjectedSessionEntry } from "@earendil-works/pi-coding-agent";
|
|
2
|
-
import {
|
|
3
|
-
|
|
4
|
-
editableMessage,
|
|
5
|
-
messageTokens,
|
|
6
|
-
withContent,
|
|
7
|
-
} from "./context.ts";
|
|
8
|
-
import { toolCallsById } from "./tool-calls.ts";
|
|
2
|
+
import { type Edit, messageTokens, withContent } from "./context.ts";
|
|
3
|
+
import { newestToolResults, type ToolResult } from "./tool-calls.ts";
|
|
9
4
|
|
|
10
5
|
export interface PruneOptions {
|
|
11
6
|
/** Newest tool-output tokens that are never pruned. */
|
|
@@ -22,41 +17,44 @@ export function pruneToolOutputs(
|
|
|
22
17
|
edited: ReadonlySet<string>,
|
|
23
18
|
options: PruneOptions,
|
|
24
19
|
): Edit[] {
|
|
25
|
-
const calls = toolCallsById(entries);
|
|
26
20
|
const edits: Edit[] = [];
|
|
27
21
|
let seen = 0;
|
|
28
22
|
let savings = 0;
|
|
29
23
|
|
|
30
|
-
for (
|
|
31
|
-
const
|
|
32
|
-
const message = entry && editableMessage(entry);
|
|
33
|
-
if (!entry || message?.role !== "toolResult") continue;
|
|
34
|
-
const tokens = messageTokens(message);
|
|
24
|
+
for (const result of newestToolResults(entries)) {
|
|
25
|
+
const tokens = messageTokens(result.message);
|
|
35
26
|
const protectedByWindow = seen < options.protectTokens;
|
|
36
27
|
seen += tokens;
|
|
37
|
-
const id = entry.sourceEntry.id;
|
|
38
28
|
if (
|
|
39
29
|
protectedByWindow ||
|
|
40
30
|
tokens < options.minTokens ||
|
|
41
|
-
edited.has(id) ||
|
|
42
|
-
isSkillFile(
|
|
31
|
+
edited.has(result.id) ||
|
|
32
|
+
isSkillFile(result.args)
|
|
43
33
|
) {
|
|
44
34
|
continue;
|
|
45
35
|
}
|
|
46
|
-
const
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
},
|
|
51
|
-
];
|
|
52
|
-
const saved = tokens - messageTokens(withContent(message, content));
|
|
53
|
-
if (saved <= 0) continue;
|
|
54
|
-
savings += saved;
|
|
55
|
-
edits.push({ targetId: id, content });
|
|
36
|
+
const edit = pruneEdit(result, tokens);
|
|
37
|
+
if (!edit) continue;
|
|
38
|
+
savings += edit.saved;
|
|
39
|
+
edits.push(edit.edit);
|
|
56
40
|
}
|
|
57
41
|
return savings >= options.minSavings ? edits.reverse() : [];
|
|
58
42
|
}
|
|
59
43
|
|
|
44
|
+
function pruneEdit(
|
|
45
|
+
{ id, message }: ToolResult,
|
|
46
|
+
tokens: number,
|
|
47
|
+
): { edit: Edit; saved: number } | undefined {
|
|
48
|
+
const content = [
|
|
49
|
+
{
|
|
50
|
+
type: "text" as const,
|
|
51
|
+
text: `[Output pruned: about ${tokens} tokens. Call recall with entryId "${id}" to read it.]`,
|
|
52
|
+
},
|
|
53
|
+
];
|
|
54
|
+
const saved = tokens - messageTokens(withContent(message, content));
|
|
55
|
+
return saved > 0 ? { edit: { targetId: id, content }, saved } : undefined;
|
|
56
|
+
}
|
|
57
|
+
|
|
60
58
|
function isSkillFile(args: Record<string, unknown> | undefined): boolean {
|
|
61
59
|
const path = args?.path;
|
|
62
60
|
return typeof path === "string" && /(^|[\\/])SKILL\.md$/.test(path);
|
package/src/shake.ts
CHANGED
|
@@ -26,7 +26,8 @@ const BLOCK =
|
|
|
26
26
|
|
|
27
27
|
/**
|
|
28
28
|
* Elides large blocks and images from older messages. Tool calls and thinking stay intact,
|
|
29
|
-
* so every tool call keeps its result
|
|
29
|
+
* so every tool call keeps its result. Signatures stay valid, but Anthropic drops every thinking
|
|
30
|
+
* block after the first changed message.
|
|
30
31
|
*/
|
|
31
32
|
export function shake(
|
|
32
33
|
entries: readonly ProjectedSessionEntry[],
|
|
@@ -43,22 +44,30 @@ export function shake(
|
|
|
43
44
|
for (const message of entry.messages) {
|
|
44
45
|
if (message.role !== "system") seen += messageTokens(message);
|
|
45
46
|
}
|
|
46
|
-
const
|
|
47
|
-
if (
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
if (content === undefined) continue;
|
|
51
|
-
const saved =
|
|
52
|
-
messageTokens(message) - messageTokens(withContent(message, content));
|
|
53
|
-
if (saved <= 0) continue;
|
|
54
|
-
savings += saved;
|
|
55
|
-
edits.push({ targetId: entry.sourceEntry.id, content });
|
|
47
|
+
const edit = isProtected ? undefined : shakeEdit(entry, options);
|
|
48
|
+
if (!edit) continue;
|
|
49
|
+
savings += edit.saved;
|
|
50
|
+
edits.push(edit.edit);
|
|
56
51
|
}
|
|
57
52
|
return savings >= options.minSavings && edits.length > 0
|
|
58
53
|
? edits.reverse()
|
|
59
54
|
: [];
|
|
60
55
|
}
|
|
61
56
|
|
|
57
|
+
function shakeEdit(
|
|
58
|
+
entry: ProjectedSessionEntry,
|
|
59
|
+
options: ShakeOptions,
|
|
60
|
+
): { edit: Edit; saved: number } | undefined {
|
|
61
|
+
const message = editableMessage(entry);
|
|
62
|
+
if (!message || message.role === "user") return undefined;
|
|
63
|
+
const targetId = entry.sourceEntry.id;
|
|
64
|
+
const content = shakeContent(message, targetId, options);
|
|
65
|
+
if (content === undefined) return undefined;
|
|
66
|
+
const saved =
|
|
67
|
+
messageTokens(message) - messageTokens(withContent(message, content));
|
|
68
|
+
return saved > 0 ? { edit: { targetId, content }, saved } : undefined;
|
|
69
|
+
}
|
|
70
|
+
|
|
62
71
|
function shakeContent(
|
|
63
72
|
message: EditableMessage,
|
|
64
73
|
id: string,
|
package/src/stale.ts
CHANGED
|
@@ -1,13 +1,7 @@
|
|
|
1
1
|
import type { ToolResultMessage } from "@earendil-works/pi-ai";
|
|
2
2
|
import type { ProjectedSessionEntry } from "@earendil-works/pi-coding-agent";
|
|
3
|
-
import {
|
|
4
|
-
|
|
5
|
-
editableMessage,
|
|
6
|
-
messageTokens,
|
|
7
|
-
suffixTokens,
|
|
8
|
-
withContent,
|
|
9
|
-
} from "./context.ts";
|
|
10
|
-
import { toolCallsById } from "./tool-calls.ts";
|
|
3
|
+
import { type Edit, messageTokens, withContent } from "./context.ts";
|
|
4
|
+
import { newestToolResults, type ToolResult } from "./tool-calls.ts";
|
|
11
5
|
|
|
12
6
|
export const SUPERSEDED_NOTICE = "[Superseded by a newer read of this file]";
|
|
13
7
|
|
|
@@ -26,62 +20,63 @@ interface NewerReads {
|
|
|
26
20
|
/**
|
|
27
21
|
* Replaces read results that a newer read of the same file makes redundant.
|
|
28
22
|
* A newer full read covers every older read; a newer ranged read covers only the same range;
|
|
29
|
-
* a failed read covers only older failed reads.
|
|
30
|
-
* within `suffixLimit` tokens.
|
|
23
|
+
* a failed read covers only older failed reads.
|
|
31
24
|
*/
|
|
32
25
|
export function supersededReads(
|
|
33
26
|
entries: readonly ProjectedSessionEntry[],
|
|
34
27
|
edited: ReadonlySet<string>,
|
|
35
|
-
suffixLimit: number,
|
|
36
28
|
): Edit[] {
|
|
37
|
-
const calls = toolCallsById(entries);
|
|
38
|
-
const suffix = suffixTokens(entries);
|
|
39
29
|
const newer = new Map<string, NewerReads>();
|
|
40
30
|
const edits: Edit[] = [];
|
|
41
31
|
|
|
42
|
-
for (
|
|
43
|
-
const
|
|
44
|
-
const message = entry && editableMessage(entry);
|
|
45
|
-
if (!entry || message?.role !== "toolResult" || message.toolName !== "read")
|
|
46
|
-
continue;
|
|
47
|
-
const key = readKey(calls.get(message.toolCallId)?.arguments);
|
|
32
|
+
for (const result of newestToolResults(entries)) {
|
|
33
|
+
const key = result.message.toolName === "read" && readKey(result.args);
|
|
48
34
|
if (!key) continue;
|
|
49
|
-
|
|
50
35
|
const seen = newer.get(key.path) ?? {
|
|
51
36
|
anyRead: false,
|
|
52
37
|
fullSuccess: false,
|
|
53
38
|
successRanges: new Set<string>(),
|
|
54
39
|
};
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
? seen.anyRead
|
|
59
|
-
: seen.fullSuccess ||
|
|
60
|
-
(key.range !== undefined && seen.successRanges.has(key.range));
|
|
61
|
-
|
|
62
|
-
if (
|
|
63
|
-
superseded &&
|
|
64
|
-
!edited.has(entry.sourceEntry.id) &&
|
|
65
|
-
(suffix[i] ?? Number.POSITIVE_INFINITY) <= suffixLimit
|
|
66
|
-
) {
|
|
67
|
-
const content = [{ type: "text" as const, text: SUPERSEDED_NOTICE }];
|
|
68
|
-
if (
|
|
69
|
-
messageTokens(withContent(message, content)) < messageTokens(message)
|
|
70
|
-
) {
|
|
71
|
-
edits.push({ targetId: entry.sourceEntry.id, content });
|
|
72
|
-
}
|
|
73
|
-
}
|
|
74
|
-
|
|
75
|
-
seen.anyRead = true;
|
|
76
|
-
if (readCoversOutput) {
|
|
77
|
-
if (key.range === undefined) seen.fullSuccess = true;
|
|
78
|
-
else seen.successRanges.add(key.range);
|
|
40
|
+
if (!edited.has(result.id) && isSuperseded(result, key, seen)) {
|
|
41
|
+
const edit = supersededEdit(result);
|
|
42
|
+
if (edit) edits.push(edit);
|
|
79
43
|
}
|
|
44
|
+
recordRead(seen, result, key);
|
|
80
45
|
newer.set(key.path, seen);
|
|
81
46
|
}
|
|
82
47
|
return edits.reverse();
|
|
83
48
|
}
|
|
84
49
|
|
|
50
|
+
function isSuperseded(
|
|
51
|
+
{ message }: ToolResult,
|
|
52
|
+
key: ReadKey,
|
|
53
|
+
seen: NewerReads,
|
|
54
|
+
): boolean {
|
|
55
|
+
if (message.isError) return seen.anyRead;
|
|
56
|
+
return (
|
|
57
|
+
seen.fullSuccess ||
|
|
58
|
+
(key.range !== undefined && seen.successRanges.has(key.range))
|
|
59
|
+
);
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
function supersededEdit({ id, message }: ToolResult): Edit | undefined {
|
|
63
|
+
const content = [{ type: "text" as const, text: SUPERSEDED_NOTICE }];
|
|
64
|
+
return messageTokens(withContent(message, content)) < messageTokens(message)
|
|
65
|
+
? { targetId: id, content }
|
|
66
|
+
: undefined;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
function recordRead(
|
|
70
|
+
seen: NewerReads,
|
|
71
|
+
{ message }: ToolResult,
|
|
72
|
+
key: ReadKey,
|
|
73
|
+
): void {
|
|
74
|
+
seen.anyRead = true;
|
|
75
|
+
if (message.isError || isTruncatedRead(message.content)) return;
|
|
76
|
+
if (key.range === undefined) seen.fullSuccess = true;
|
|
77
|
+
else seen.successRanges.add(key.range);
|
|
78
|
+
}
|
|
79
|
+
|
|
85
80
|
function isTruncatedRead(content: ToolResultMessage["content"]): boolean {
|
|
86
81
|
return content.some(
|
|
87
82
|
(block) =>
|
package/src/tool-calls.ts
CHANGED
|
@@ -1,8 +1,15 @@
|
|
|
1
1
|
import type { ToolCall } from "@earendil-works/pi-ai";
|
|
2
2
|
import type { ProjectedSessionEntry } from "@earendil-works/pi-coding-agent";
|
|
3
|
+
import { type EditableMessage, editableMessage } from "./context.ts";
|
|
4
|
+
|
|
5
|
+
export interface ToolResult {
|
|
6
|
+
id: string;
|
|
7
|
+
message: Extract<EditableMessage, { role: "toolResult" }>;
|
|
8
|
+
args: Record<string, unknown> | undefined;
|
|
9
|
+
}
|
|
3
10
|
|
|
4
11
|
/** Tool calls in the projected context, by tool call ID. */
|
|
5
|
-
|
|
12
|
+
function toolCallsById(
|
|
6
13
|
entries: readonly ProjectedSessionEntry[],
|
|
7
14
|
): Map<string, ToolCall> {
|
|
8
15
|
const calls = new Map<string, ToolCall>();
|
|
@@ -16,3 +23,17 @@ export function toolCallsById(
|
|
|
16
23
|
}
|
|
17
24
|
return calls;
|
|
18
25
|
}
|
|
26
|
+
|
|
27
|
+
/** Editable tool results, newest first, with the arguments of their tool call. */
|
|
28
|
+
export function* newestToolResults(
|
|
29
|
+
entries: readonly ProjectedSessionEntry[],
|
|
30
|
+
): Generator<ToolResult> {
|
|
31
|
+
const calls = toolCallsById(entries);
|
|
32
|
+
for (let i = entries.length - 1; i >= 0; i--) {
|
|
33
|
+
const entry = entries[i];
|
|
34
|
+
const message = entry && editableMessage(entry);
|
|
35
|
+
if (!entry || message?.role !== "toolResult") continue;
|
|
36
|
+
const args = calls.get(message.toolCallId)?.arguments;
|
|
37
|
+
yield { id: entry.sourceEntry.id, message, args };
|
|
38
|
+
}
|
|
39
|
+
}
|
package/CHANGELOG.md
DELETED
|
@@ -1,31 +0,0 @@
|
|
|
1
|
-
# Changelog
|
|
2
|
-
|
|
3
|
-
## Unreleased
|
|
4
|
-
|
|
5
|
-
## 0.2.1
|
|
6
|
-
|
|
7
|
-
- Rewrite the README for users who do not know Pi internals: it explains the terms, the sequence of a session, and each setting with its default and an example.
|
|
8
|
-
|
|
9
|
-
## 0.2.0
|
|
10
|
-
|
|
11
|
-
- Send handoff note requests with the session's thinking level and tool choice, so Anthropic reuses the cached conversation instead of re-billing it; reject notes that call a tool.
|
|
12
|
-
- `soft` now writes Pi's summary at `thresholdTokens` or `thresholdPercent`, so an earlier threshold compacts even when no handoff note is available. Before, Pi compacted only at its own threshold.
|
|
13
|
-
- Keep older read results when a newer full or ranged read is truncated, count the replaced read in the stale suffix budget, and preserve user-role messages during shaking.
|
|
14
|
-
- Bound recall regex searches in a worker and propagate cancellation; keep regex syntax errors and result paging.
|
|
15
|
-
- Reject length-truncated or oversized handoff notes, validate retained-context budgets, and use only ready background notes during native, manual, and overflow compaction.
|
|
16
|
-
- Apply the configured strategy order at both custom and Pi thresholds, including while a background note is unfinished; scale the background-note lead with small thresholds.
|
|
17
|
-
- Preserve projected retained history after earlier compactions and context edits; keep Pi's token estimate when maintenance makes no edits.
|
|
18
|
-
- Clarify measured provider behavior, fallback paths, and metadata-only image recall.
|
|
19
|
-
|
|
20
|
-
- `contextKit` settings, named after the `compaction.*` settings of oh-my-pi: `enabled`, `thresholdTokens`, `thresholdPercent`, `methodOrder`, `asyncEnabled`, `supersedeReads`, and the prune and shake budgets.
|
|
21
|
-
- An earlier threshold compacts at the end of a turn, without interrupting the run.
|
|
22
|
-
- The background note starts one eighth of the threshold early, capped at 32,000 tokens.
|
|
23
|
-
- By default, a handoff note is tried before shaking.
|
|
24
|
-
- A failed threshold note is not retried until the next compaction.
|
|
25
|
-
|
|
26
|
-
## 0.1.0
|
|
27
|
-
|
|
28
|
-
- Superseded read replacement at the end of each turn.
|
|
29
|
-
- Pruning of old tool outputs and elision of old blocks and images above the compaction threshold.
|
|
30
|
-
- Handoff compaction from the live context, with a background note near the threshold.
|
|
31
|
-
- `recall` tool for the full session history.
|