pi-context-kit 0.3.2 → 0.4.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.
@@ -0,0 +1,106 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://unpkg.com/pi-context-kit/context-kit.schema.json",
4
+ "title": "pi-context-kit settings",
5
+ "description": "~/.pi/agent/context-kit.json, or .pi/context-kit.json in a trusted project.",
6
+ "type": "object",
7
+ "additionalProperties": false,
8
+ "properties": {
9
+ "$schema": { "type": "string" },
10
+ "enabled": {
11
+ "description": "false stops context maintenance and handoff notes. recall stays available.",
12
+ "type": "boolean",
13
+ "default": true
14
+ },
15
+ "threshold": {
16
+ "description": "Where maintenance starts: a number of tokens, a share of the context window such as \"75%\", or \"pi\" for Pi's own compaction threshold.",
17
+ "default": "75%",
18
+ "oneOf": [
19
+ { "type": "integer", "minimum": 1 },
20
+ { "type": "string", "pattern": "^(0*100(\\.0+)?|0*[1-9]\\d?(\\.\\d+)?|0+\\.\\d*[1-9]\\d*)%$" },
21
+ { "const": "pi" }
22
+ ]
23
+ },
24
+ "strategy": {
25
+ "description": "balanced: handoff note written in the background, then shake, then Pi's summary. frugal: shake first, no background calls. pi-summary: Pi's summary only.",
26
+ "enum": ["balanced", "frugal", "pi-summary"],
27
+ "default": "balanced"
28
+ },
29
+ "advanced": {
30
+ "type": "object",
31
+ "additionalProperties": false,
32
+ "properties": {
33
+ "methodOrder": {
34
+ "description": "Replaces the method order of the strategy. Methods after \"soft\" never run.",
35
+ "type": "array",
36
+ "items": { "enum": ["handoff", "shake", "soft"] }
37
+ },
38
+ "background": {
39
+ "description": "Write the handoff note in the background before the threshold. The strategy sets the default.",
40
+ "type": "boolean"
41
+ },
42
+ "supersedeReads": {
43
+ "description": "Replace an older read of a file that was read again.",
44
+ "type": "boolean",
45
+ "default": true
46
+ },
47
+ "progressRatio": {
48
+ "description": "Each method must bring the context to this fraction of the threshold, or the next method runs.",
49
+ "type": "number",
50
+ "exclusiveMinimum": 0,
51
+ "maximum": 1,
52
+ "default": 0.8
53
+ },
54
+ "prune": {
55
+ "type": "object",
56
+ "additionalProperties": false,
57
+ "properties": {
58
+ "enabled": { "type": "boolean", "default": true },
59
+ "protectTokens": {
60
+ "description": "The newest tool outputs, up to this many tokens, are never pruned.",
61
+ "type": "integer",
62
+ "minimum": 0,
63
+ "default": 40000
64
+ },
65
+ "minSavings": {
66
+ "description": "Prune only when this many tokens or more are removed.",
67
+ "type": "integer",
68
+ "minimum": 0,
69
+ "default": 20000
70
+ },
71
+ "minTokens": {
72
+ "description": "Tool outputs smaller than this are never pruned.",
73
+ "type": "integer",
74
+ "minimum": 0,
75
+ "default": 50
76
+ }
77
+ }
78
+ },
79
+ "shake": {
80
+ "type": "object",
81
+ "additionalProperties": false,
82
+ "properties": {
83
+ "protectTokens": {
84
+ "description": "The newest context, up to this many tokens, is never shaken.",
85
+ "type": "integer",
86
+ "minimum": 0,
87
+ "default": 16000
88
+ },
89
+ "minSavings": {
90
+ "description": "Shake only when this many tokens or more are removed.",
91
+ "type": "integer",
92
+ "minimum": 0,
93
+ "default": 4000
94
+ },
95
+ "blockMinTokens": {
96
+ "description": "Code and XML blocks smaller than this are never shaken.",
97
+ "type": "integer",
98
+ "minimum": 0,
99
+ "default": 400
100
+ }
101
+ }
102
+ }
103
+ }
104
+ }
105
+ }
106
+ }
@@ -1,4 +1,6 @@
1
+ import { existsSync } from "node:fs";
1
2
  import { type Api, type Message, type Model } from "@earendil-works/pi-ai";
3
+ import { Container, SettingsList, Text } from "@earendil-works/pi-tui";
2
4
  import { Type } from "typebox";
3
5
  import {
4
6
  convertToLlm,
@@ -7,11 +9,14 @@ import {
7
9
  type ExtensionContext,
8
10
  findCutPoint,
9
11
  generateSummaryWithUsage,
12
+ getAgentDir,
10
13
  getLatestCompactionEntry,
14
+ getSettingsListTheme,
11
15
  type ProjectedSessionEntry,
12
16
  type SessionBeforeCompactEvent,
13
17
  type SessionEntry,
14
18
  SettingsManager,
19
+ type Theme,
15
20
  } from "@earendil-works/pi-coding-agent";
16
21
  import {
17
22
  BackgroundHandoff,
@@ -20,11 +25,12 @@ import {
20
25
  type Note,
21
26
  } from "../src/background.ts";
22
27
  import {
28
+ before,
23
29
  type ContextKitConfig,
24
- type Method,
25
30
  ownThreshold,
26
31
  readConfig,
27
32
  speculationLead,
33
+ writesHandoff,
28
34
  } from "../src/config.ts";
29
35
  import {
30
36
  applyEdits,
@@ -36,26 +42,48 @@ import {
36
42
  import { handoffSummary } from "../src/handoff.ts";
37
43
  import { type MaintenancePlan, planMaintenance } from "../src/maintain.ts";
38
44
  import { requestNote } from "../src/note.ts";
45
+ import { migrateLegacy, migrateProject } from "../src/migrate.ts";
39
46
  import { readEntry, searchEntries } from "../src/recall.ts";
47
+ import { panelItems, settingValue, summaryText } from "../src/panel.ts";
48
+ import {
49
+ createSettings,
50
+ loadSettings,
51
+ readSettingsFile,
52
+ saveSetting,
53
+ settingsPaths,
54
+ } from "../src/settings-file.ts";
55
+ import { freedNotice, statusText } from "../src/status.ts";
40
56
 
41
57
  // One closure per session: Pi and pi-subagents load the extension once per session in the same process.
42
58
  export default function contextKit(pi: ExtensionAPI): void {
43
- const background = new BackgroundHandoff();
59
+ /** The latest context, so a background note that finishes between turns updates the status. */
60
+ let statusContext: ExtensionContext | undefined;
61
+ const background = new BackgroundHandoff(() => {
62
+ if (!statusContext) return;
63
+ try {
64
+ showStatus(statusContext);
65
+ } catch {
66
+ // Pi throws on a ctx of a replaced session, which has no footer left to update.
67
+ statusContext = undefined;
68
+ }
69
+ });
44
70
  let reported = "";
45
71
  /** The compaction epoch in which a threshold note failed, so it is not retried every turn. */
46
72
  let failedEpoch: string | null | undefined;
47
73
  /** The same for Pi's summary at the extension's own threshold. */
48
74
  let softFailedEpoch: string | null | undefined;
49
75
 
50
- /** Reads `contextKit` from Pi's settings on each use, so `/reload` and project settings apply. */
76
+ const paths = (ctx: ExtensionContext) =>
77
+ settingsPaths(getAgentDir(), ctx.cwd, ctx.isProjectTrusted());
78
+
79
+ /** Reads the settings files on each use, so a change applies at the next turn. */
51
80
  const settings = (ctx: ExtensionContext): ContextKitConfig => {
52
- const { config, problems } = readConfig(
53
- Reflect.get(pi.getSettings(), "contextKit"),
54
- );
55
- const message = problems.join("; ");
81
+ const files = loadSettings(paths(ctx));
82
+ const { config, problems } = readConfig(files.raw);
83
+ const message = [...files.problems, ...problems].join("; ");
56
84
  if (message && message !== reported)
57
85
  ctx.ui.notify(
58
- `pi-context-kit: invalid settings, defaults used (${message}).`,
86
+ `pi-context-kit settings need attention: ${message}. Type /context-kit to see them.`,
59
87
  "warning",
60
88
  );
61
89
  reported = message;
@@ -93,6 +121,48 @@ export default function contextKit(pi: ExtensionAPI): void {
93
121
  const epoch = (branch: SessionEntry[]) =>
94
122
  getLatestCompactionEntry(branch)?.id ?? null;
95
123
 
124
+ const statusOf = (
125
+ ctx: ExtensionContext,
126
+ config: ContextKitConfig,
127
+ tokens: number,
128
+ ) => {
129
+ if (!config.enabled) return "Context cleanup off";
130
+ const model = ctx.model;
131
+ if (!model || model.contextWindow <= 0) return undefined;
132
+ return statusText({
133
+ tokens,
134
+ limit: threshold(model, config),
135
+ contextWindow: model.contextWindow,
136
+ note: background.noteState(epoch(ctx.sessionManager.getBranch())),
137
+ });
138
+ };
139
+
140
+ function showStatus(
141
+ ctx: ExtensionContext,
142
+ config = settings(ctx),
143
+ tokens = liveTokens(ctx),
144
+ ) {
145
+ statusContext = ctx;
146
+ ctx.ui.setStatus("context-kit", statusOf(ctx, config, tokens));
147
+ }
148
+
149
+ /** Pi shows compactions but not context edits, so the user learns about them here. */
150
+ const persist = (turn: Turn) => {
151
+ const output = persisted(turn.result, turn.limit);
152
+ // Both counts use the same estimate; Pi's usage count is not comparable.
153
+ const count = (edits: MaintenancePlan["edits"]) =>
154
+ contextTokens(projectedMessages(applyEdits(turn.entries, edits)));
155
+ // Maintenance needs a model with a context window, so `window` is set whenever `output` is.
156
+ const window = turn.ctx.model?.contextWindow;
157
+ if (output && window)
158
+ turn.ctx.ui.notify(
159
+ freedNotice(count([]), count(turn.result.edits), window),
160
+ "info",
161
+ );
162
+ showStatus(turn.ctx, turn.config, turn.result.tokens);
163
+ return output;
164
+ };
165
+
96
166
  const warn = (
97
167
  ctx: ExtensionContext,
98
168
  error: unknown,
@@ -227,7 +297,7 @@ export default function contextKit(pi: ExtensionAPI): void {
227
297
  messages: () => Message[],
228
298
  ) => {
229
299
  const { ctx, config, model, limit, result } = turn;
230
- if (!config.asyncEnabled || !keptEntryId) return;
300
+ if (!config.background || !keptEntryId) return;
231
301
  if (result.tokens <= limit - speculationLead(limit)) return;
232
302
  if (result.tokens > limit) return;
233
303
  const budget = Math.floor(
@@ -295,7 +365,7 @@ export default function contextKit(pi: ExtensionAPI): void {
295
365
  }
296
366
  } catch (error) {
297
367
  if (!signal.aborted)
298
- warn(ctx, error, "The remaining methods in methodOrder are tried.");
368
+ warn(ctx, error, "The next methods of the strategy are tried.");
299
369
  }
300
370
  failedEpoch = current;
301
371
  return undefined;
@@ -329,7 +399,10 @@ export default function contextKit(pi: ExtensionAPI): void {
329
399
 
330
400
  pi.on("turn_end", async (event, ctx) => {
331
401
  const config = settings(ctx);
332
- if (!config.enabled) return undefined;
402
+ if (!config.enabled) {
403
+ showStatus(ctx, config);
404
+ return undefined;
405
+ }
333
406
  const branch = ctx.sessionManager.getBranch();
334
407
  const current = epoch(branch);
335
408
  background.invalidate(current, branch);
@@ -365,7 +438,7 @@ export default function contextKit(pi: ExtensionAPI): void {
365
438
  const handed = before(methods, "handoff", "soft")
366
439
  ? await handoffAtTurn(turn)
367
440
  : undefined;
368
- if (handed === "waiting") return persisted(turn.result, limit);
441
+ if (handed === "waiting") return persist(turn);
369
442
  if (handed) return handed;
370
443
  if (
371
444
  turn.result.tokens > limit &&
@@ -373,7 +446,7 @@ export default function contextKit(pi: ExtensionAPI): void {
373
446
  before(methods, "shake", "soft")
374
447
  )
375
448
  turn.result = plan(true);
376
- return (await softAtTurn(turn)) ?? persisted(turn.result, limit);
449
+ return (await softAtTurn(turn)) ?? persist(turn);
377
450
  });
378
451
 
379
452
  const handoffBeforeCompact = async (
@@ -429,9 +502,132 @@ export default function contextKit(pi: ExtensionAPI): void {
429
502
  pi.on("session_tree", (_event, ctx) => {
430
503
  const branch = ctx.sessionManager.getBranch();
431
504
  background.invalidate(epoch(branch), branch);
505
+ showStatus(ctx);
506
+ });
507
+ /** Writes the 0.3 settings of each scope to its own file, unless that file exists. */
508
+ const migrate = (ctx: ExtensionContext) => {
509
+ const { global, project } = paths(ctx);
510
+ const piSettings = SettingsManager.create(ctx.cwd, getAgentDir(), {
511
+ projectTrusted: ctx.isProjectTrusted(),
512
+ });
513
+ // Pi reports its own unreadable settings. The project file depends on the global block, so
514
+ // neither moves until Pi reads both.
515
+ if (piSettings.drainErrors().length > 0) return;
516
+ const oldGlobal: unknown = Reflect.get(
517
+ piSettings.getGlobalSettings(),
518
+ "contextKit",
519
+ );
520
+ const oldProject: unknown = Reflect.get(
521
+ piSettings.getProjectSettings(),
522
+ "contextKit",
523
+ );
524
+ const scopes = [
525
+ { old: oldGlobal, file: global, content: () => migrateLegacy(oldGlobal) },
526
+ {
527
+ old: oldProject,
528
+ file: project,
529
+ // Runs after the global file is written, which the project file then overrides.
530
+ content: () =>
531
+ migrateProject(oldGlobal, oldProject, readSettingsFile(global)),
532
+ },
533
+ ];
534
+ for (const { old, file, content } of scopes) {
535
+ if (old === undefined || !file) continue;
536
+ try {
537
+ if (!createSettings(file, content())) continue;
538
+ } catch (error) {
539
+ warn(ctx, error, "Defaults apply until it works.", `saving ${file}`);
540
+ // The project file depends on the global file, so both wait for the next start.
541
+ return;
542
+ }
543
+ ctx.ui.notify(
544
+ `pi-context-kit moved its settings to ${file}. The "contextKit" entry in Pi's settings.json is no longer used.`,
545
+ "info",
546
+ );
547
+ }
548
+ };
549
+
550
+ pi.on("session_start", (_event, ctx) => {
551
+ migrate(ctx);
552
+ showStatus(ctx);
553
+ });
554
+ // A compaction returned from turn_end emits no session_compact.
555
+ pi.on("agent_end", (_event, ctx) => showStatus(ctx));
556
+ pi.on("session_compact", (_event, ctx) => {
557
+ background.cancel();
558
+ showStatus(ctx);
559
+ });
560
+ pi.on("session_shutdown", () => {
561
+ background.cancel();
562
+ statusContext = undefined;
563
+ });
564
+
565
+ /** Returns whether the setting was saved. */
566
+ const choose = (ctx: ExtensionContext, id: string, value: string) => {
567
+ try {
568
+ saveSetting(paths(ctx), id, settingValue(id, value));
569
+ return true;
570
+ } catch (error) {
571
+ const message = error instanceof Error ? error.message : String(error);
572
+ ctx.ui.notify(`pi-context-kit: ${message}`, "error");
573
+ return false;
574
+ } finally {
575
+ showStatus(ctx);
576
+ }
577
+ };
578
+
579
+ const panelHeader = (ctx: ExtensionContext, theme: Theme) => {
580
+ const status = statusOf(ctx, settings(ctx), liveTokens(ctx)) ?? "";
581
+ const { global, project } = paths(ctx);
582
+ const files =
583
+ project && existsSync(project)
584
+ ? `${global}, and for this project ${project}`
585
+ : global;
586
+ return `${theme.fg("accent", theme.bold("pi-context-kit"))} ${status}\n${theme.fg("dim", `Saved in ${files}`)}`;
587
+ };
588
+
589
+ pi.registerCommand("context-kit", {
590
+ description: "Show and change pi-context-kit settings",
591
+ handler: async (_args, ctx) => {
592
+ // The settings warning points here, so it shows again.
593
+ reported = "";
594
+ const config = settings(ctx);
595
+ if (ctx.mode !== "tui") {
596
+ ctx.ui.notify(summaryText(config, paths(ctx).global), "info");
597
+ return;
598
+ }
599
+ await ctx.ui.custom<undefined>((tui, theme, _keybindings, done) => {
600
+ const items = panelItems(config);
601
+ const saved = new Map<string, string>(
602
+ items.map((item) => [item.id, item.currentValue]),
603
+ );
604
+ const header = new Text(panelHeader(ctx, theme));
605
+ const list = new SettingsList(
606
+ items,
607
+ items.length,
608
+ getSettingsListTheme(),
609
+ (id, value) => {
610
+ // The list shows the new value before this runs.
611
+ if (choose(ctx, id, value)) saved.set(id, value);
612
+ else list.updateValue(id, saved.get(id) ?? value);
613
+ header.setText(panelHeader(ctx, theme));
614
+ },
615
+ () => done(undefined),
616
+ );
617
+ const container = new Container();
618
+ container.addChild(header);
619
+ container.addChild(list);
620
+ return {
621
+ render: (width: number) => container.render(width),
622
+ invalidate: () => container.invalidate(),
623
+ handleInput: (data: string) => {
624
+ list.handleInput(data);
625
+ tui.requestRender();
626
+ },
627
+ };
628
+ });
629
+ },
432
630
  });
433
- pi.on("session_compact", () => background.cancel());
434
- pi.on("session_shutdown", () => background.cancel());
435
631
 
436
632
  pi.registerTool({
437
633
  name: "recall",
@@ -519,7 +715,11 @@ function currentTokens(
519
715
  }
520
716
 
521
717
  function handoffEnabled(config: ContextKitConfig): boolean {
522
- return config.enabled && before(config.methodOrder, "handoff", "soft");
718
+ return config.enabled && writesHandoff(config.methodOrder);
719
+ }
720
+
721
+ function liveTokens(ctx: ExtensionContext): number {
722
+ return ctx.getContextUsage()?.tokens ?? contextTokens(liveMessages(ctx));
523
723
  }
524
724
 
525
725
  function liveMessages(ctx: ExtensionContext): Message[] {
@@ -551,18 +751,6 @@ function fits(
551
751
  return Math.ceil(summary.length / 4) + kept <= limit * ratio;
552
752
  }
553
753
 
554
- /** Soft ends the extension's strategy chain, even when other methods follow it. */
555
- function before(methods: readonly Method[], a: Method, b: Method): boolean {
556
- const index = methods.indexOf(a);
557
- const other = methods.indexOf(b);
558
- const soft = methods.indexOf("soft");
559
- const stop = Math.min(
560
- other >= 0 ? other : Number.POSITIVE_INFINITY,
561
- soft >= 0 ? soft : Number.POSITIVE_INFINITY,
562
- );
563
- return index >= 0 && index < stop;
564
- }
565
-
566
754
  /** Finds the retained boundary from model-visible entries, including prior compaction tails and edits. */
567
755
  function recentStart(
568
756
  ctx: ExtensionContext,
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pi-context-kit",
3
- "version": "0.3.2",
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.",
3
+ "version": "0.4.1",
4
+ "description": "Keep long Pi coding agent sessions sharp. Clears old file reads and tool outputs from the context, writes the compaction summary in the background, and lets the agent recall the original text.",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "author": "HugoLopes45 (https://github.com/HugoLopes45)",
@@ -29,7 +29,9 @@
29
29
  ],
30
30
  "files": [
31
31
  "extensions",
32
- "src"
32
+ "src",
33
+ "context-kit.schema.json",
34
+ "CHANGELOG.md"
33
35
  ],
34
36
  "engines": {
35
37
  "node": ">=22.19.0"
@@ -42,17 +44,18 @@
42
44
  "scripts": {
43
45
  "check": "tsc --noEmit && npm run lint && vitest --run",
44
46
  "lint": "node scripts/lint.ts",
45
- "test": "vitest --run",
46
- "prepublishOnly": "test -n \"$GITHUB_ACTIONS\" || test \"$(npm whoami)\" = hugolopes45 || { echo 'Publish only as the npm user hugolopes45.' >&2; exit 1; }; npm run check"
47
+ "prepublishOnly": "npm run check"
47
48
  },
48
49
  "peerDependencies": {
49
50
  "@earendil-works/pi-ai": "*",
50
51
  "@earendil-works/pi-coding-agent": "*",
52
+ "@earendil-works/pi-tui": "*",
51
53
  "typebox": "*"
52
54
  },
53
55
  "devDependencies": {
54
56
  "@earendil-works/pi-ai": "^1.5.2",
55
57
  "@earendil-works/pi-coding-agent": "^1.5.2",
58
+ "@earendil-works/pi-tui": "^1.5.2",
56
59
  "@types/node": "^26.6.4",
57
60
  "eslint": "^10.14.0",
58
61
  "typebox": "^1.3.27",
package/src/background.ts CHANGED
@@ -18,11 +18,19 @@ interface Job {
18
18
  controller: AbortController;
19
19
  note: Promise<Note | undefined>;
20
20
  settled: boolean;
21
+ /** Whether the job settled with a note. */
22
+ ready: boolean;
21
23
  }
22
24
 
23
25
  /** One speculative handoff note per compaction epoch, written while the agent keeps working. */
24
26
  export class BackgroundHandoff {
25
27
  #job: Job | undefined;
28
+ readonly #onSettle: () => void;
29
+
30
+ /** `onSettle` runs when the current job finishes, with or without a note. */
31
+ constructor(onSettle: () => void = () => {}) {
32
+ this.#onSettle = onSettle;
33
+ }
26
34
 
27
35
  /** Starts a job unless one already ran in this epoch. */
28
36
  start(
@@ -39,10 +47,23 @@ export class BackgroundHandoff {
39
47
  if (!controller.signal.aborted) onError(error);
40
48
  return undefined;
41
49
  })
42
- .finally(() => {
50
+ .then((result) => {
43
51
  job.settled = true;
52
+ job.ready = result !== undefined;
53
+ return result;
44
54
  });
45
- const job: Job = { epoch, leafId, controller, note, settled: false };
55
+ // Apart from `note`, so the listener cannot fail the note. The listener must not throw.
56
+ void note.then(() => {
57
+ if (this.#job === job) this.#onSettle();
58
+ });
59
+ const job: Job = {
60
+ epoch,
61
+ leafId,
62
+ controller,
63
+ note,
64
+ settled: false,
65
+ ready: false,
66
+ };
46
67
  this.#job = job;
47
68
  return true;
48
69
  }
@@ -52,6 +73,14 @@ export class BackgroundHandoff {
52
73
  return this.#job?.epoch === epoch && !this.#job.settled;
53
74
  }
54
75
 
76
+ /** The background note of this epoch, for the status line. */
77
+ noteState(epoch: string | null): "writing" | "ready" | undefined {
78
+ const job = this.#job;
79
+ if (job?.epoch !== epoch) return undefined;
80
+ if (!job.settled) return "writing";
81
+ return job.ready ? "ready" : undefined;
82
+ }
83
+
55
84
  /** Returns a finished note only when it still covers a prefix of the branch. */
56
85
  async takeReady(
57
86
  epoch: string | null,