pi-context-kit 0.0.0-stage → 0.2.0
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 +28 -0
- package/LICENSE +21 -0
- package/README.md +106 -2
- package/extensions/index.ts +509 -0
- package/package.json +49 -4
- package/src/background.ts +104 -0
- package/src/config.ts +228 -0
- package/src/context.ts +108 -0
- package/src/files.ts +54 -0
- package/src/handoff.ts +83 -0
- package/src/maintain.ts +79 -0
- package/src/note.ts +34 -0
- package/src/prune.ts +63 -0
- package/src/recall.ts +212 -0
- package/src/shake.ts +106 -0
- package/src/stale.ts +106 -0
- package/src/tool-calls.ts +18 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## Unreleased
|
|
4
|
+
|
|
5
|
+
- 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.
|
|
6
|
+
- `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.
|
|
7
|
+
|
|
8
|
+
## 0.2.0
|
|
9
|
+
|
|
10
|
+
- 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.
|
|
11
|
+
- Bound recall regex searches in a worker and propagate cancellation; keep regex syntax errors and result paging.
|
|
12
|
+
- Reject length-truncated or oversized handoff notes, validate retained-context budgets, and use only ready background notes during native, manual, and overflow compaction.
|
|
13
|
+
- 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.
|
|
14
|
+
- Preserve projected retained history after earlier compactions and context edits; keep Pi's token estimate when maintenance makes no edits.
|
|
15
|
+
- Clarify measured provider behavior, fallback paths, and metadata-only image recall.
|
|
16
|
+
|
|
17
|
+
- `contextKit` settings, named after the `compaction.*` settings of oh-my-pi: `enabled`, `thresholdTokens`, `thresholdPercent`, `methodOrder`, `asyncEnabled`, `supersedeReads`, and the prune and shake budgets.
|
|
18
|
+
- An earlier threshold compacts at the end of a turn, without interrupting the run.
|
|
19
|
+
- The background note starts one eighth of the threshold early, capped at 32,000 tokens.
|
|
20
|
+
- By default, a handoff note is tried before shaking.
|
|
21
|
+
- A failed threshold note is not retried until the next compaction.
|
|
22
|
+
|
|
23
|
+
## 0.1.0
|
|
24
|
+
|
|
25
|
+
- Superseded read replacement at the end of each turn.
|
|
26
|
+
- Pruning of old tool outputs and elision of old blocks and images above the compaction threshold.
|
|
27
|
+
- Handoff compaction from the live context, with a background note near the threshold.
|
|
28
|
+
- `recall` tool for the full session history.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 HugoLopes45
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,107 @@
|
|
|
1
|
-
#
|
|
1
|
+
# pi-context-kit
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Context maintenance for [Pi](https://github.com/earendil-works/pi). It uses the active session model for handoff notes; if that request fails or cannot fit, Pi's summary remains the fallback. Offline integration tests use Pi's faux provider.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
pi install npm:pi-context-kit
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## What it does
|
|
12
|
+
|
|
13
|
+
| When | Action |
|
|
14
|
+
| --- | --- |
|
|
15
|
+
| End of each turn | Replaces older reads only when a newer successful read covers them. Truncated whole-file reads do not cover older ranges. Replacements are limited by `staleSuffixTokens`; this is not a guarantee about provider prompt caching. |
|
|
16
|
+
| End of a turn above the threshold | Prunes old tool outputs. It keeps the edits only if they bring the context to 80% of the threshold or less. Otherwise the methods in `methodOrder` run. |
|
|
17
|
+
| Before the threshold | Can write a handoff note in the background from the live context. Its lead is one eighth of the threshold, capped at 32,000 tokens. |
|
|
18
|
+
| Compaction | Uses a ready background note without waiting. Otherwise it may write a fresh note when the retained context can fit the target. Failed, truncated, oversized, or unavailable notes fall back to Pi's summary. |
|
|
19
|
+
| Any time | `recall` searches or reads raw entries on the current branch, including compacted and context-edited messages. Images are represented by MIME metadata, not recovered image pixels. Regex searches run in a worker with a deadline. |
|
|
20
|
+
|
|
21
|
+
Automatic maintenance runs between model requests:
|
|
22
|
+
|
|
23
|
+
- At Pi's threshold, Pi compacts between two model requests and the run continues.
|
|
24
|
+
- At an earlier `thresholdTokens` or `thresholdPercent`, a handoff is appended only when the retained context and note fit the progress target. Otherwise maintenance continues in the configured order. The extension never calls `ctx.compact()`, which aborts the run.
|
|
25
|
+
- The kept part always holds the latest messages and tool results.
|
|
26
|
+
- An early automatic handoff can defer while a relevant background note is still being written. Native, manual, and overflow compaction never wait for an unfinished note.
|
|
27
|
+
|
|
28
|
+
Notes:
|
|
29
|
+
|
|
30
|
+
- The handoff note uses the same sections as Pi's summary. It also gets Pi's `<read-files>` and `<modified-files>` sections, which cover the whole branch.
|
|
31
|
+
- `/compact <focus>` requests a fresh note for that focus when the retained context leaves enough room. Otherwise Pi handles the request.
|
|
32
|
+
- After a context overflow, a ready background note is used. Otherwise Pi's summary runs, because the live context no longer fits the model.
|
|
33
|
+
- User-role messages are never shaken, preserving instructions and images. Tool calls and thinking blocks are never edited; each tool call keeps its result, and signed reasoning stays valid. Images removed from eligible tool outputs can only be recalled as metadata.
|
|
34
|
+
- With Pi's compaction disabled, only superseded reads are replaced.
|
|
35
|
+
- The note request uses the session's thinking level and tool choice, because Anthropic drops the cached messages when either differs. A reply that calls a tool is rejected. The request caps output to the available budget. Providers can differ; failures use Pi's summary. Prompt-cache reuse is provider-dependent and is not guaranteed.
|
|
36
|
+
- Subagents run the extension in their own sessions with their own settings. Without a UI, warnings are not shown.
|
|
37
|
+
|
|
38
|
+
## Settings
|
|
39
|
+
|
|
40
|
+
Add a `contextKit` object to `~/.pi/agent/settings.json` or `.pi/settings.json`. Project settings override global settings. Changes apply after `/reload` or a restart. An invalid value shows a warning and keeps its default. The names follow the `compaction.*` settings of oh-my-pi.
|
|
41
|
+
|
|
42
|
+
```json
|
|
43
|
+
{
|
|
44
|
+
"contextKit": {
|
|
45
|
+
"thresholdTokens": 150000,
|
|
46
|
+
"methodOrder": ["handoff", "shake", "soft"]
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
| Setting | Default | Description |
|
|
52
|
+
| --- | --- | --- |
|
|
53
|
+
| `enabled` | `true` | Set to `false` to disable maintenance and handoff compaction. `recall` stays available. |
|
|
54
|
+
| `thresholdTokens` | `-1` | Starts automatic maintenance above this token count. Overrides `thresholdPercent`. `-1` uses `thresholdPercent`. |
|
|
55
|
+
| `thresholdPercent` | `-1` | Starts automatic maintenance above this percentage of the context window, at most 99%. `-1` uses Pi's threshold only. |
|
|
56
|
+
| `methodOrder` | `["handoff", "shake", "soft"]` | What runs, in order, when pruning is not enough. `handoff`: a note by the session model. `shake`: elides large old code or XML blocks and images, without a model call. `soft`: Pi's summary, written at this threshold when it is below Pi's own. `remote` and `snapcompact` are accepted and skipped, because Pi lacks them. |
|
|
57
|
+
| `asyncEnabled` | `true` | Writes the handoff note in the background before the threshold. |
|
|
58
|
+
| `supersedeReads` | `true` | Replaces older reads of a file that was read again. |
|
|
59
|
+
| `staleSuffixTokens` | `8000` | Replaces superseded reads only when the entire replaced entry and newer suffix fit this many tokens. |
|
|
60
|
+
| `progressRatio` | `0.8` | Pruning, shaking, and handoff notes must reduce the estimated context to this fraction of the threshold. |
|
|
61
|
+
| `prune.enabled` | `true` | Prunes old tool outputs above the threshold. |
|
|
62
|
+
| `prune.protectTokens` | `40000` | Newest tool-output tokens that are never pruned. |
|
|
63
|
+
| `prune.minSavings` | `20000` | Prunes nothing unless the savings reach this many tokens. |
|
|
64
|
+
| `prune.minTokens` | `50` | Outputs smaller than this are never pruned. |
|
|
65
|
+
| `shake.protectTokens` | `16000` | Newest context tokens that are never shaken; user-role messages are always protected. |
|
|
66
|
+
| `shake.minSavings` | `4000` | Shakes nothing unless the savings reach this many tokens. |
|
|
67
|
+
| `shake.blockMinTokens` | `400` | Blocks smaller than this stay. |
|
|
68
|
+
|
|
69
|
+
`methodOrder` controls end-of-turn maintenance. `soft` ends that sequence: below Pi's threshold it compacts with Pi's summary, which updates any previous summary; methods after `soft` do not run. A failed or unavailable handoff can fall back to `shake` before `soft`.
|
|
70
|
+
|
|
71
|
+
Pi's compaction hook cannot append context edits. Manual compaction, overflow recovery, and compaction triggered before a turn can use a handoff note or Pi's summary, but cannot run `shake` there.
|
|
72
|
+
|
|
73
|
+
Pi still compacts at its own threshold (`compaction.reserveTokens`, `compaction.modelOverrides`). Earlier thresholds request maintenance, not guaranteed compaction: an oversized retained tool result may leave no room for a useful note or summary, and a failed summary is not retried until the next compaction. Budget checks use Pi's token estimates; actual provider token counts and cache behavior can differ.
|
|
74
|
+
|
|
75
|
+
## Development
|
|
76
|
+
|
|
77
|
+
```sh
|
|
78
|
+
npm install
|
|
79
|
+
npm run check
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
The tests run offline with Pi's faux provider.
|
|
83
|
+
|
|
84
|
+
## Contributing and releases
|
|
85
|
+
|
|
86
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) for local checks and pull requests. Report vulnerabilities through [SECURITY.md](SECURITY.md), not public issues.
|
|
87
|
+
|
|
88
|
+
1. Open a pull request. CI runs `npm run check` on Node 22 and 24.
|
|
89
|
+
2. Add user-visible changes under `## Unreleased` in `CHANGELOG.md`.
|
|
90
|
+
3. Choose `patch` for fixes, `minor` for compatible features, or `major` for breaking changes.
|
|
91
|
+
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.
|
|
92
|
+
5. Merge the release PR, then wait for CI to succeed on the exact `main` commit you want to publish.
|
|
93
|
+
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.
|
|
94
|
+
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`.
|
|
95
|
+
8. Approve the `npm` environment deployment. The owner can approve their own run; no third-party approval is needed.
|
|
96
|
+
|
|
97
|
+
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.
|
|
98
|
+
|
|
99
|
+
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.
|
|
100
|
+
|
|
101
|
+
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.
|
|
102
|
+
|
|
103
|
+
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.
|
|
104
|
+
|
|
105
|
+
## License
|
|
106
|
+
|
|
107
|
+
MIT
|
|
@@ -0,0 +1,509 @@
|
|
|
1
|
+
import {
|
|
2
|
+
type Api,
|
|
3
|
+
type Message,
|
|
4
|
+
type Model,
|
|
5
|
+
Type,
|
|
6
|
+
} from "@earendil-works/pi-ai";
|
|
7
|
+
import {
|
|
8
|
+
convertToLlm,
|
|
9
|
+
type ExtensionAPI,
|
|
10
|
+
type ExtensionContext,
|
|
11
|
+
findCutPoint,
|
|
12
|
+
generateSummaryWithUsage,
|
|
13
|
+
getLatestCompactionEntry,
|
|
14
|
+
type SessionEntry,
|
|
15
|
+
SettingsManager,
|
|
16
|
+
} from "@earendil-works/pi-coding-agent";
|
|
17
|
+
import {
|
|
18
|
+
BackgroundHandoff,
|
|
19
|
+
type BackgroundNote,
|
|
20
|
+
firstEntryAfter,
|
|
21
|
+
type Note,
|
|
22
|
+
} from "../src/background.ts";
|
|
23
|
+
import {
|
|
24
|
+
type ContextKitConfig,
|
|
25
|
+
type Method,
|
|
26
|
+
ownThreshold,
|
|
27
|
+
readConfig,
|
|
28
|
+
speculationLead,
|
|
29
|
+
} from "../src/config.ts";
|
|
30
|
+
import {
|
|
31
|
+
applyEdits,
|
|
32
|
+
contextTokens,
|
|
33
|
+
editedEntryIds,
|
|
34
|
+
projectedMessages,
|
|
35
|
+
toDrafts,
|
|
36
|
+
} from "../src/context.ts";
|
|
37
|
+
import { handoffSummary } from "../src/handoff.ts";
|
|
38
|
+
import { planMaintenance } from "../src/maintain.ts";
|
|
39
|
+
import { requestNote } from "../src/note.ts";
|
|
40
|
+
import { readEntry, searchEntries } from "../src/recall.ts";
|
|
41
|
+
|
|
42
|
+
// One closure per session: Pi and pi-subagents load the extension once per session in the same process.
|
|
43
|
+
export default function contextKit(pi: ExtensionAPI): void {
|
|
44
|
+
const background = new BackgroundHandoff();
|
|
45
|
+
let reported = "";
|
|
46
|
+
/** The compaction epoch in which a threshold note failed, so it is not retried every turn. */
|
|
47
|
+
let failedEpoch: string | null | undefined;
|
|
48
|
+
/** The same for Pi's summary at the extension's own threshold. */
|
|
49
|
+
let softFailedEpoch: string | null | undefined;
|
|
50
|
+
|
|
51
|
+
/** Reads `contextKit` from Pi's settings on each use, so `/reload` and project settings apply. */
|
|
52
|
+
const settings = (ctx: ExtensionContext): ContextKitConfig => {
|
|
53
|
+
const { config, problems } = readConfig(
|
|
54
|
+
Reflect.get(pi.getSettings(), "contextKit"),
|
|
55
|
+
);
|
|
56
|
+
const message = problems.join("; ");
|
|
57
|
+
if (message && message !== reported)
|
|
58
|
+
ctx.ui.notify(
|
|
59
|
+
`pi-context-kit: invalid settings, defaults used (${message}).`,
|
|
60
|
+
"warning",
|
|
61
|
+
);
|
|
62
|
+
reported = message;
|
|
63
|
+
return config;
|
|
64
|
+
};
|
|
65
|
+
|
|
66
|
+
const reasoning = () => {
|
|
67
|
+
const level = pi.getThinkingLevel();
|
|
68
|
+
return level === "off" ? undefined : level;
|
|
69
|
+
};
|
|
70
|
+
|
|
71
|
+
const compactionSettings = (model: Model<Api>) =>
|
|
72
|
+
SettingsManager.inMemory(pi.getSettings()).getCompactionSettings(model);
|
|
73
|
+
|
|
74
|
+
/** Pi compacts above this many tokens, using the same settings lookup as Pi. */
|
|
75
|
+
const piThreshold = (model: Model<Api> | undefined): number => {
|
|
76
|
+
if (!model || model.contextWindow <= 0) return Number.POSITIVE_INFINITY;
|
|
77
|
+
const compaction = compactionSettings(model);
|
|
78
|
+
return compaction.enabled
|
|
79
|
+
? model.contextWindow - compaction.reserveTokens
|
|
80
|
+
: Number.POSITIVE_INFINITY;
|
|
81
|
+
};
|
|
82
|
+
|
|
83
|
+
/** Pi still compacts at its own threshold, so a configured threshold can only come earlier. */
|
|
84
|
+
const threshold = (
|
|
85
|
+
model: Model<Api> | undefined,
|
|
86
|
+
config: ContextKitConfig,
|
|
87
|
+
): number => {
|
|
88
|
+
const piLimit = piThreshold(model);
|
|
89
|
+
return model && piLimit < Number.POSITIVE_INFINITY
|
|
90
|
+
? Math.min(piLimit, ownThreshold(config, model.contextWindow))
|
|
91
|
+
: piLimit;
|
|
92
|
+
};
|
|
93
|
+
|
|
94
|
+
const epoch = (branch: SessionEntry[]) =>
|
|
95
|
+
getLatestCompactionEntry(branch)?.id ?? null;
|
|
96
|
+
|
|
97
|
+
const warn = (
|
|
98
|
+
ctx: ExtensionContext,
|
|
99
|
+
error: unknown,
|
|
100
|
+
fallback: string,
|
|
101
|
+
what = "handoff note",
|
|
102
|
+
) => {
|
|
103
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
104
|
+
ctx.ui.notify(
|
|
105
|
+
`pi-context-kit: ${what} failed (${message}). ${fallback}`,
|
|
106
|
+
"warning",
|
|
107
|
+
);
|
|
108
|
+
};
|
|
109
|
+
|
|
110
|
+
/** Pi's summary at the extension's threshold, because Pi's own hook waits for Pi's threshold. */
|
|
111
|
+
const soft = async (input: {
|
|
112
|
+
ctx: ExtensionContext;
|
|
113
|
+
model: Model<Api>;
|
|
114
|
+
config: ContextKitConfig;
|
|
115
|
+
branch: SessionEntry[];
|
|
116
|
+
entries: Parameters<typeof projectedMessages>[0];
|
|
117
|
+
limit: number;
|
|
118
|
+
}) => {
|
|
119
|
+
const { ctx, model, config, limit } = input;
|
|
120
|
+
const { keepRecentTokens, reserveTokens } = compactionSettings(model);
|
|
121
|
+
const keptEntryId = recentStart(ctx, keepRecentTokens);
|
|
122
|
+
if (!keptEntryId) return undefined;
|
|
123
|
+
const retained = keptTokens(ctx, keptEntryId);
|
|
124
|
+
if (!fits("", retained, limit, config.progressRatio)) return undefined;
|
|
125
|
+
const start = input.entries.findIndex(
|
|
126
|
+
(entry) => entry.sourceEntry.id === keptEntryId,
|
|
127
|
+
);
|
|
128
|
+
// As in Pi, the previous summary goes to the update prompt, not into the history.
|
|
129
|
+
const previous = input.entries.findIndex(
|
|
130
|
+
(entry) =>
|
|
131
|
+
entry.sourceEntry.type === "compaction" && entry.messages.length > 0,
|
|
132
|
+
);
|
|
133
|
+
if (start <= previous + 1) return undefined;
|
|
134
|
+
const source = input.entries[previous]?.sourceEntry;
|
|
135
|
+
const { text, usage } = await generateSummaryWithUsage(
|
|
136
|
+
projectedMessages(input.entries.slice(previous + 1, start)),
|
|
137
|
+
model,
|
|
138
|
+
reserveTokens,
|
|
139
|
+
undefined,
|
|
140
|
+
undefined,
|
|
141
|
+
ctx.signal,
|
|
142
|
+
undefined,
|
|
143
|
+
source?.type === "compaction" ? source.summary : undefined,
|
|
144
|
+
pi.getThinkingLevel(),
|
|
145
|
+
// The registry resolves auth per request, as for handoff notes.
|
|
146
|
+
(model, context, options) =>
|
|
147
|
+
ctx.modelRegistry.streamSimple(model, context, options),
|
|
148
|
+
undefined,
|
|
149
|
+
undefined,
|
|
150
|
+
undefined,
|
|
151
|
+
ctx.sessionManager.getSessionId(),
|
|
152
|
+
);
|
|
153
|
+
const summary = handoffSummary(text, input.branch);
|
|
154
|
+
return fits(summary.summary, retained, limit, config.progressRatio)
|
|
155
|
+
? { ...summary, firstKeptEntryId: keptEntryId, usage }
|
|
156
|
+
: undefined;
|
|
157
|
+
};
|
|
158
|
+
|
|
159
|
+
/**
|
|
160
|
+
* Builds a handoff compaction. A background note keeps everything after its leaf. A new note
|
|
161
|
+
* covers the whole context and keeps from `keptEntryId`, so the latest work stays visible.
|
|
162
|
+
*/
|
|
163
|
+
const handoff = async (input: {
|
|
164
|
+
ctx: ExtensionContext;
|
|
165
|
+
model: Model<Api>;
|
|
166
|
+
config: ContextKitConfig;
|
|
167
|
+
branch: SessionEntry[];
|
|
168
|
+
ready: BackgroundNote | undefined;
|
|
169
|
+
keptEntryId: string;
|
|
170
|
+
limit: number;
|
|
171
|
+
/** Undefined when only the background note may be used. */
|
|
172
|
+
messages: Message[] | undefined;
|
|
173
|
+
focus?: string;
|
|
174
|
+
signal: AbortSignal;
|
|
175
|
+
cancelBackground: () => void;
|
|
176
|
+
}) => {
|
|
177
|
+
const { ctx, branch, ready } = input;
|
|
178
|
+
const compaction = (note: Note, firstKeptEntryId: string) => ({
|
|
179
|
+
...handoffSummary(note.note, branch),
|
|
180
|
+
firstKeptEntryId,
|
|
181
|
+
usage: note.usage,
|
|
182
|
+
});
|
|
183
|
+
if (ready) {
|
|
184
|
+
const result = compaction(
|
|
185
|
+
ready,
|
|
186
|
+
firstEntryAfter(branch, ready.leafId) ?? input.keptEntryId,
|
|
187
|
+
);
|
|
188
|
+
const kept = keptTokens(ctx, result.firstKeptEntryId);
|
|
189
|
+
if (fits(result.summary, kept, input.limit, input.config.progressRatio))
|
|
190
|
+
return result;
|
|
191
|
+
}
|
|
192
|
+
const retained = keptTokens(ctx, input.keptEntryId);
|
|
193
|
+
const availableTokens = Math.floor(
|
|
194
|
+
input.limit * input.config.progressRatio - retained,
|
|
195
|
+
);
|
|
196
|
+
if (!input.messages || availableTokens <= 0) {
|
|
197
|
+
input.cancelBackground();
|
|
198
|
+
return undefined;
|
|
199
|
+
}
|
|
200
|
+
input.cancelBackground();
|
|
201
|
+
const note = await requestNote({
|
|
202
|
+
registry: ctx.modelRegistry,
|
|
203
|
+
model: input.model,
|
|
204
|
+
sessionId: ctx.sessionManager.getSessionId(),
|
|
205
|
+
messages: input.messages,
|
|
206
|
+
reasoning: reasoning(),
|
|
207
|
+
focus: input.focus,
|
|
208
|
+
signal: input.signal,
|
|
209
|
+
maxTokens: Math.min(input.model.maxTokens, availableTokens),
|
|
210
|
+
});
|
|
211
|
+
if (!note) return undefined;
|
|
212
|
+
const result = compaction(note, input.keptEntryId);
|
|
213
|
+
return fits(
|
|
214
|
+
result.summary,
|
|
215
|
+
retained,
|
|
216
|
+
input.limit,
|
|
217
|
+
input.config.progressRatio,
|
|
218
|
+
)
|
|
219
|
+
? result
|
|
220
|
+
: undefined;
|
|
221
|
+
};
|
|
222
|
+
|
|
223
|
+
pi.on("turn_end", async (event, ctx) => {
|
|
224
|
+
const config = settings(ctx);
|
|
225
|
+
if (!config.enabled) return undefined;
|
|
226
|
+
const model = ctx.model;
|
|
227
|
+
const limit = threshold(model, config);
|
|
228
|
+
const methods = config.methodOrder;
|
|
229
|
+
const entries = event.context.contextEntries;
|
|
230
|
+
const branch = ctx.sessionManager.getBranch();
|
|
231
|
+
const edited = editedEntryIds(branch);
|
|
232
|
+
const tokens =
|
|
233
|
+
ctx.getContextUsage()?.tokens ??
|
|
234
|
+
contextTokens(projectedMessages(entries));
|
|
235
|
+
const plan = (shake: boolean) =>
|
|
236
|
+
planMaintenance({
|
|
237
|
+
entries,
|
|
238
|
+
edited,
|
|
239
|
+
options: { ...config, shake: shake ? config.shake : undefined },
|
|
240
|
+
tokens,
|
|
241
|
+
threshold: limit,
|
|
242
|
+
});
|
|
243
|
+
const shakeFirst = before(methods, "shake", "handoff");
|
|
244
|
+
let result = plan(shakeFirst);
|
|
245
|
+
const drafts = () => toDrafts(result.edits);
|
|
246
|
+
|
|
247
|
+
const leafId = ctx.sessionManager.getLeafId();
|
|
248
|
+
const current = epoch(branch);
|
|
249
|
+
background.invalidate(current, branch);
|
|
250
|
+
// Try ordered strategies at Pi's threshold before its native hook can compact.
|
|
251
|
+
const own = result.tokens > limit;
|
|
252
|
+
if (model && leafId && before(methods, "handoff", "soft")) {
|
|
253
|
+
const messages = () =>
|
|
254
|
+
convertToLlm(projectedMessages(applyEdits(entries, result.edits)));
|
|
255
|
+
const keepRecentTokens = compactionSettings(model).keepRecentTokens;
|
|
256
|
+
const keptEntryId = own ? recentStart(ctx, keepRecentTokens) : undefined;
|
|
257
|
+
const speculativeKeptId = recentStart(ctx, keepRecentTokens);
|
|
258
|
+
const speculativeBudget = speculativeKeptId
|
|
259
|
+
? Math.floor(
|
|
260
|
+
limit * config.progressRatio - keptTokens(ctx, speculativeKeptId),
|
|
261
|
+
)
|
|
262
|
+
: 0;
|
|
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;
|
|
347
|
+
});
|
|
348
|
+
|
|
349
|
+
pi.on("session_before_compact", async (event, ctx) => {
|
|
350
|
+
const model = ctx.model;
|
|
351
|
+
const config = settings(ctx);
|
|
352
|
+
if (
|
|
353
|
+
!model ||
|
|
354
|
+
!config.enabled ||
|
|
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);
|
|
363
|
+
try {
|
|
364
|
+
const current = currentEpoch;
|
|
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
|
+
);
|
|
393
|
+
} catch (error) {
|
|
394
|
+
if (!signal.aborted) warn(ctx, error, "Pi's summary is used instead.");
|
|
395
|
+
return undefined;
|
|
396
|
+
}
|
|
397
|
+
});
|
|
398
|
+
|
|
399
|
+
pi.on("session_compact", () => background.cancel());
|
|
400
|
+
pi.on("session_shutdown", () => background.cancel());
|
|
401
|
+
|
|
402
|
+
pi.registerTool({
|
|
403
|
+
name: "recall",
|
|
404
|
+
label: "Recall",
|
|
405
|
+
description:
|
|
406
|
+
"Search or read the full session history, including messages removed by compaction and tool outputs that were pruned or elided. " +
|
|
407
|
+
"Pass `query` to list matching entries with their IDs, newest first. Pass `entryId` to read one entry in full.",
|
|
408
|
+
parameters: Type.Object({
|
|
409
|
+
query: Type.Optional(
|
|
410
|
+
Type.String({ description: "Text to find, case-insensitive." }),
|
|
411
|
+
),
|
|
412
|
+
regex: Type.Optional(
|
|
413
|
+
Type.Boolean({ description: "Treat query as a regular expression." }),
|
|
414
|
+
),
|
|
415
|
+
entryId: Type.Optional(
|
|
416
|
+
Type.String({ description: "ID of the entry to read." }),
|
|
417
|
+
),
|
|
418
|
+
offset: Type.Optional(
|
|
419
|
+
Type.Number({
|
|
420
|
+
description:
|
|
421
|
+
"Matches or characters to skip, as given in the previous result.",
|
|
422
|
+
}),
|
|
423
|
+
),
|
|
424
|
+
limit: Type.Optional(
|
|
425
|
+
Type.Number({
|
|
426
|
+
description: "Maximum matches or characters to return.",
|
|
427
|
+
}),
|
|
428
|
+
),
|
|
429
|
+
}),
|
|
430
|
+
async execute(_toolCallId, params, signal, _onUpdate, ctx) {
|
|
431
|
+
const branch = ctx.sessionManager.getBranch();
|
|
432
|
+
let text: string;
|
|
433
|
+
if (params.entryId) text = readEntry(branch, params.entryId, params);
|
|
434
|
+
else if (params.query)
|
|
435
|
+
text = await searchEntries(
|
|
436
|
+
branch,
|
|
437
|
+
{ ...params, query: params.query },
|
|
438
|
+
signal,
|
|
439
|
+
);
|
|
440
|
+
else throw new Error("Pass query or entryId.");
|
|
441
|
+
return { content: [{ type: "text", text }], details: undefined };
|
|
442
|
+
},
|
|
443
|
+
});
|
|
444
|
+
}
|
|
445
|
+
|
|
446
|
+
function liveMessages(ctx: ExtensionContext): Message[] {
|
|
447
|
+
return convertToLlm(ctx.sessionManager.buildSessionProjection().messages);
|
|
448
|
+
}
|
|
449
|
+
|
|
450
|
+
/** Tokens of the system prompt plus the projected context from `firstKeptEntryId` on. */
|
|
451
|
+
function keptTokens(ctx: ExtensionContext, firstKeptEntryId: string): number {
|
|
452
|
+
const entries = ctx.sessionManager.buildSessionProjection().entries;
|
|
453
|
+
const start = entries.findIndex(
|
|
454
|
+
(entry) => entry.sourceEntry.id === firstKeptEntryId,
|
|
455
|
+
);
|
|
456
|
+
if (start < 0) return Number.POSITIVE_INFINITY;
|
|
457
|
+
const system = projectedMessages(entries)
|
|
458
|
+
.filter((message) => message.role === "system")
|
|
459
|
+
.at(-1);
|
|
460
|
+
return contextTokens([
|
|
461
|
+
...(system ? [system] : []),
|
|
462
|
+
...projectedMessages(entries.slice(start)),
|
|
463
|
+
]);
|
|
464
|
+
}
|
|
465
|
+
|
|
466
|
+
function fits(
|
|
467
|
+
summary: string,
|
|
468
|
+
kept: number,
|
|
469
|
+
limit: number,
|
|
470
|
+
ratio: number,
|
|
471
|
+
): boolean {
|
|
472
|
+
return Math.ceil(summary.length / 4) + kept <= limit * ratio;
|
|
473
|
+
}
|
|
474
|
+
|
|
475
|
+
/** Soft ends the extension's strategy chain, even when other methods follow it. */
|
|
476
|
+
function before(methods: readonly Method[], a: Method, b: Method): boolean {
|
|
477
|
+
const index = methods.indexOf(a);
|
|
478
|
+
const other = methods.indexOf(b);
|
|
479
|
+
const soft = methods.indexOf("soft");
|
|
480
|
+
const stop = Math.min(
|
|
481
|
+
other >= 0 ? other : Number.POSITIVE_INFINITY,
|
|
482
|
+
soft >= 0 ? soft : Number.POSITIVE_INFINITY,
|
|
483
|
+
);
|
|
484
|
+
return index >= 0 && index < stop;
|
|
485
|
+
}
|
|
486
|
+
|
|
487
|
+
/** Finds the retained boundary from model-visible entries, including prior compaction tails and edits. */
|
|
488
|
+
function recentStart(
|
|
489
|
+
ctx: ExtensionContext,
|
|
490
|
+
keepRecentTokens: number,
|
|
491
|
+
): string | undefined {
|
|
492
|
+
const entries: SessionEntry[] = [];
|
|
493
|
+
for (const projected of ctx.sessionManager.buildSessionProjection().entries) {
|
|
494
|
+
const source = projected.sourceEntry;
|
|
495
|
+
if (source.type === "compaction") continue;
|
|
496
|
+
for (const message of projected.messages) {
|
|
497
|
+
if (message.role === "system") continue;
|
|
498
|
+
entries.push({
|
|
499
|
+
type: "message",
|
|
500
|
+
id: source.id,
|
|
501
|
+
parentId: source.parentId,
|
|
502
|
+
timestamp: source.timestamp,
|
|
503
|
+
message,
|
|
504
|
+
});
|
|
505
|
+
}
|
|
506
|
+
}
|
|
507
|
+
const cut = findCutPoint(entries, 0, entries.length, keepRecentTokens);
|
|
508
|
+
return entries[cut.firstKeptEntryIndex]?.id;
|
|
509
|
+
}
|