pi-context-kit 0.4.2 → 0.4.4

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.
Files changed (39) hide show
  1. package/CHANGELOG.md +22 -8
  2. package/LICENSE +1 -1
  3. package/README.md +162 -151
  4. package/context-kit.schema.json +62 -78
  5. package/extensions/index.ts +279 -256
  6. package/node_modules/pi-hl-utils/LICENSE +21 -0
  7. package/node_modules/pi-hl-utils/package.json +47 -0
  8. package/node_modules/pi-hl-utils/src/errors.ts +9 -0
  9. package/node_modules/pi-hl-utils/src/evidence.ts +363 -0
  10. package/node_modules/pi-hl-utils/src/expand-on-click.ts +90 -0
  11. package/node_modules/pi-hl-utils/src/layered-settings.ts +513 -0
  12. package/node_modules/pi-hl-utils/src/null-optional-arguments.ts +147 -0
  13. package/node_modules/pi-hl-utils/src/pi-agent-session-discovery.ts +48 -0
  14. package/node_modules/pi-hl-utils/src/record.ts +3 -0
  15. package/node_modules/pi-hl-utils/src/settings-command.ts +213 -0
  16. package/node_modules/pi-hl-utils/src/settings-menu.ts +477 -0
  17. package/node_modules/pi-hl-utils/src/token-calibration.ts +39 -0
  18. package/node_modules/pi-hl-utils/src/ui.ts +355 -0
  19. package/package.json +42 -44
  20. package/src/background.ts +2 -3
  21. package/src/command.ts +17 -0
  22. package/src/config.ts +3 -207
  23. package/src/context-kit-settings.ts +152 -0
  24. package/src/context.ts +43 -16
  25. package/src/files.ts +6 -13
  26. package/src/handoff.ts +3 -7
  27. package/src/maintain.ts +6 -19
  28. package/src/menu.ts +159 -0
  29. package/src/migrate.ts +99 -19
  30. package/src/note.ts +5 -6
  31. package/src/prune.ts +2 -1
  32. package/src/recall.ts +14 -37
  33. package/src/settings-file.ts +13 -101
  34. package/src/shake.ts +6 -12
  35. package/src/stale.ts +22 -26
  36. package/src/status.ts +2 -6
  37. package/src/tool-calls.ts +2 -3
  38. package/README.zh-CN.md +0 -387
  39. package/src/panel.ts +0 -89
@@ -1,7 +1,6 @@
1
- import { existsSync } from "node:fs";
2
- import { type Api, type Message, type Model } from "@earendil-works/pi-ai";
3
- import { Container, SettingsList, Text } from "@earendil-works/pi-tui";
4
- import { Type } from "typebox";
1
+ import { existsSync, renameSync } from "node:fs";
2
+
3
+ import { type Api, getCurrentSystemMessage, type Message, type Model } from "@earendil-works/pi-ai";
5
4
  import {
6
5
  convertToLlm,
7
6
  type CompactionEntryDraft,
@@ -11,27 +10,43 @@ import {
11
10
  generateSummaryWithUsage,
12
11
  getAgentDir,
13
12
  getLatestCompactionEntry,
14
- getSettingsListTheme,
15
13
  type ProjectedSessionEntry,
16
14
  type SessionBeforeCompactEvent,
17
15
  type SessionEntry,
18
16
  SettingsManager,
19
- type Theme,
17
+ type TurnEndEvent,
20
18
  } from "@earendil-works/pi-coding-agent";
19
+ import { errorText } from "pi-hl-utils/errors";
20
+ import {
21
+ layeredMenuScopes,
22
+ layeredSettingsSession,
23
+ type LayeredSettingScope,
24
+ type LayeredSettingSource,
25
+ } from "pi-hl-utils/layered-settings";
26
+ import { registerSettingsCommand } from "pi-hl-utils/settings-command";
27
+ import { SettingsMenu } from "pi-hl-utils/settings-menu";
28
+ import { Type } from "typebox";
29
+
21
30
  import {
22
31
  BackgroundHandoff,
23
32
  type BackgroundNote,
24
33
  firstEntryAfter,
25
34
  type Note,
26
35
  } from "../src/background.ts";
36
+ import { contextKitCommandSpec } from "../src/command.ts";
27
37
  import {
28
38
  before,
29
39
  type ContextKitConfig,
30
40
  ownThreshold,
31
- readConfig,
32
41
  speculationLead,
33
42
  writesHandoff,
34
43
  } from "../src/config.ts";
44
+ import {
45
+ type ContextKitChange,
46
+ type ContextKitOptionsPatch,
47
+ contextKitConfig,
48
+ contextKitSettings,
49
+ } from "../src/context-kit-settings.ts";
35
50
  import {
36
51
  applyEdits,
37
52
  contextTokens,
@@ -41,17 +56,15 @@ import {
41
56
  } from "../src/context.ts";
42
57
  import { handoffSummary } from "../src/handoff.ts";
43
58
  import { type MaintenancePlan, planMaintenance } from "../src/maintain.ts";
59
+ import {
60
+ contextKitMenuSpec,
61
+ type ContextKitMenuHost,
62
+ type ContextKitMenuView,
63
+ } from "../src/menu.ts";
64
+ import { planSettingsImports, type ScopeSource, type SettingsImport } from "../src/migrate.ts";
44
65
  import { requestNote } from "../src/note.ts";
45
- import { migrateLegacy, migrateProject } from "../src/migrate.ts";
46
66
  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";
67
+ import { readSettingsFile, settingsPaths } from "../src/settings-file.ts";
55
68
  import { freedNotice, statusText } from "../src/status.ts";
56
69
 
57
70
  // One closure per session: Pi and pi-subagents load the extension once per session in the same process.
@@ -76,17 +89,33 @@ export default function contextKit(pi: ExtensionAPI): void {
76
89
  const paths = (ctx: ExtensionContext) =>
77
90
  settingsPaths(getAgentDir(), ctx.cwd, ctx.isProjectTrusted());
78
91
 
79
- /** Reads the settings files on each use, so a change applies at the next turn. */
80
- const settings = (ctx: ExtensionContext): ContextKitConfig => {
81
- const files = loadSettings(paths(ctx));
82
- const { config, problems } = readConfig(files.raw);
83
- const message = [...files.problems, ...problems].join("; ");
92
+ /** Warns once per distinct set of problems; the warning points to /context-kit. */
93
+ const report = (ctx: ExtensionContext, problems: string[]) => {
94
+ const message = problems.join("; ");
84
95
  if (message && message !== reported)
85
96
  ctx.ui.notify(
86
97
  `pi-context-kit settings need attention: ${message}. Type /context-kit to see them.`,
87
98
  "warning",
88
99
  );
89
100
  reported = message;
101
+ };
102
+
103
+ /** Reads Pi's settings files on each call, so a change applies at the next turn. */
104
+ const readSettingsOf = (ctx: ExtensionContext) => {
105
+ const session = layeredSettingsSession(ctx);
106
+ const lenient = contextKitSettings.readSettingsLeniently(session);
107
+ const { config, problems } = contextKitConfig(lenient);
108
+ return {
109
+ manager: session.settingsManager,
110
+ lenient,
111
+ config,
112
+ problems: [...lenient.invalid.map((error) => error.message), ...problems],
113
+ };
114
+ };
115
+
116
+ const settings = (ctx: ExtensionContext): ContextKitConfig => {
117
+ const { config, problems } = readSettingsOf(ctx);
118
+ report(ctx, problems);
90
119
  return config;
91
120
  };
92
121
 
@@ -108,26 +137,18 @@ export default function contextKit(pi: ExtensionAPI): void {
108
137
  };
109
138
 
110
139
  /** Pi still compacts at its own threshold, so a configured threshold can only come earlier. */
111
- const threshold = (
112
- model: Model<Api> | undefined,
113
- config: ContextKitConfig,
114
- ): number => {
140
+ const threshold = (model: Model<Api> | undefined, config: ContextKitConfig): number => {
115
141
  const piLimit = piThreshold(model);
116
142
  return model && piLimit < Number.POSITIVE_INFINITY
117
143
  ? Math.min(piLimit, ownThreshold(config, model.contextWindow))
118
144
  : piLimit;
119
145
  };
120
146
 
121
- const epoch = (branch: SessionEntry[]) =>
122
- getLatestCompactionEntry(branch)?.id ?? null;
147
+ const epoch = (branch: SessionEntry[]) => getLatestCompactionEntry(branch)?.id ?? null;
123
148
 
124
- const statusOf = (
125
- ctx: ExtensionContext,
126
- config: ContextKitConfig,
127
- tokens: number,
128
- ) => {
149
+ const statusOf = (ctx: ExtensionContext, config: ContextKitConfig, tokens: number) => {
129
150
  if (!config.enabled) return "Context cleanup off";
130
- const model = ctx.model;
151
+ const model: Model<Api> | undefined = ctx.model;
131
152
  if (!model || model.contextWindow <= 0) return undefined;
132
153
  return statusText({
133
154
  tokens,
@@ -137,11 +158,7 @@ export default function contextKit(pi: ExtensionAPI): void {
137
158
  });
138
159
  };
139
160
 
140
- function showStatus(
141
- ctx: ExtensionContext,
142
- config = settings(ctx),
143
- tokens = liveTokens(ctx),
144
- ) {
161
+ function showStatus(ctx: ExtensionContext, config = settings(ctx), tokens = liveTokens(ctx)) {
145
162
  statusContext = ctx;
146
163
  ctx.ui.setStatus("context-kit", statusOf(ctx, config, tokens));
147
164
  }
@@ -155,25 +172,14 @@ export default function contextKit(pi: ExtensionAPI): void {
155
172
  // Maintenance needs a model with a context window, so `window` is set whenever `output` is.
156
173
  const window = turn.ctx.model?.contextWindow;
157
174
  if (output && window)
158
- turn.ctx.ui.notify(
159
- freedNotice(count([]), count(turn.result.edits), window),
160
- "info",
161
- );
175
+ turn.ctx.ui.notify(freedNotice(count([]), count(turn.result.edits), window), "info");
162
176
  showStatus(turn.ctx, turn.config, turn.result.tokens);
163
177
  return output;
164
178
  };
165
179
 
166
- const warn = (
167
- ctx: ExtensionContext,
168
- error: unknown,
169
- fallback: string,
170
- what = "handoff note",
171
- ) => {
172
- const message = error instanceof Error ? error.message : String(error);
173
- ctx.ui.notify(
174
- `pi-context-kit: ${what} failed (${message}). ${fallback}`,
175
- "warning",
176
- );
180
+ const warn = (ctx: ExtensionContext, error: unknown, fallback: string, what = "handoff note") => {
181
+ const message = errorText(error);
182
+ ctx.ui.notify(`pi-context-kit: ${what} failed (${message}). ${fallback}`, "warning");
177
183
  };
178
184
 
179
185
  /** Pi's summary at the extension's threshold, because Pi's own hook waits for Pi's threshold. */
@@ -190,14 +196,12 @@ export default function contextKit(pi: ExtensionAPI): void {
190
196
  const keptEntryId = recentStart(ctx, keepRecentTokens);
191
197
  if (!keptEntryId) return undefined;
192
198
  const retained = keptTokens(ctx, keptEntryId);
193
- if (!fits("", retained, limit, config.progressRatio)) return undefined;
194
- const start = input.entries.findIndex(
195
- (entry) => entry.sourceEntry.id === keptEntryId,
196
- );
199
+ const availableTokens = Math.floor(limit * config.progressRatio - retained);
200
+ if (availableTokens <= 0) return undefined;
201
+ const start = input.entries.findIndex((entry) => entry.sourceEntry.id === keptEntryId);
197
202
  // As in Pi, the previous summary goes to the update prompt, not into the history.
198
203
  const previous = input.entries.findIndex(
199
- (entry) =>
200
- entry.sourceEntry.type === "compaction" && entry.messages.length > 0,
204
+ (entry) => entry.sourceEntry.type === "compaction" && entry.messages.length > 0,
201
205
  );
202
206
  if (start <= previous + 1) return undefined;
203
207
  const source = input.entries[previous]?.sourceEntry;
@@ -211,9 +215,13 @@ export default function contextKit(pi: ExtensionAPI): void {
211
215
  undefined,
212
216
  source?.type === "compaction" ? source.summary : undefined,
213
217
  pi.getThinkingLevel(),
214
- // The registry resolves auth per request, as for handoff notes.
218
+ // The registry resolves auth per request, as for handoff notes. Pi caps the summary only by
219
+ // the model, so a longer one would be generated and then rejected by `fits` below.
215
220
  (model, context, options) =>
216
- ctx.modelRegistry.streamSimple(model, context, options),
221
+ ctx.modelRegistry.streamSimple(model, context, {
222
+ ...options,
223
+ maxTokens: Math.min(model.maxTokens, availableTokens),
224
+ }),
217
225
  undefined,
218
226
  undefined,
219
227
  undefined,
@@ -239,7 +247,7 @@ export default function contextKit(pi: ExtensionAPI): void {
239
247
  limit: number;
240
248
  /** Undefined when only the background note may be used. */
241
249
  messages: Message[] | undefined;
242
- focus?: string;
250
+ focus?: string | undefined;
243
251
  signal: AbortSignal;
244
252
  cancelBackground: () => void;
245
253
  }) => {
@@ -250,18 +258,12 @@ export default function contextKit(pi: ExtensionAPI): void {
250
258
  usage: note.usage,
251
259
  });
252
260
  if (ready) {
253
- const result = compaction(
254
- ready,
255
- firstEntryAfter(branch, ready.leafId) ?? input.keptEntryId,
256
- );
261
+ const result = compaction(ready, firstEntryAfter(branch, ready.leafId) ?? input.keptEntryId);
257
262
  const kept = keptTokens(ctx, result.firstKeptEntryId);
258
- if (fits(result.summary, kept, input.limit, input.config.progressRatio))
259
- return result;
263
+ if (fits(result.summary, kept, input.limit, input.config.progressRatio)) return result;
260
264
  }
261
265
  const retained = keptTokens(ctx, input.keptEntryId);
262
- const availableTokens = Math.floor(
263
- input.limit * input.config.progressRatio - retained,
264
- );
266
+ const availableTokens = Math.floor(input.limit * input.config.progressRatio - retained);
265
267
  if (!input.messages || availableTokens <= 0) {
266
268
  input.cancelBackground();
267
269
  return undefined;
@@ -279,12 +281,7 @@ export default function contextKit(pi: ExtensionAPI): void {
279
281
  });
280
282
  if (!note) return undefined;
281
283
  const result = compaction(note, input.keptEntryId);
282
- return fits(
283
- result.summary,
284
- retained,
285
- input.limit,
286
- input.config.progressRatio,
287
- )
284
+ return fits(result.summary, retained, input.limit, input.config.progressRatio)
288
285
  ? result
289
286
  : undefined;
290
287
  };
@@ -300,9 +297,7 @@ export default function contextKit(pi: ExtensionAPI): void {
300
297
  if (!config.background || !keptEntryId) return;
301
298
  if (result.tokens <= limit - speculationLead(limit)) return;
302
299
  if (result.tokens > limit) return;
303
- const budget = Math.floor(
304
- limit * config.progressRatio - keptTokens(ctx, keptEntryId),
305
- );
300
+ const budget = Math.floor(limit * config.progressRatio - keptTokens(ctx, keptEntryId));
306
301
  if (budget <= 0) return;
307
302
  const context = messages();
308
303
  const maxTokens = Math.min(model.maxTokens, budget);
@@ -328,14 +323,12 @@ export default function contextKit(pi: ExtensionAPI): void {
328
323
  const { ctx, model, limit, current, result } = turn;
329
324
  const leafId = ctx.sessionManager.getLeafId();
330
325
  if (!leafId) return undefined;
331
- const messages = () =>
332
- convertToLlm(projectedMessages(applyEdits(turn.entries, result.edits)));
326
+ const messages = () => convertToLlm(projectedMessages(applyEdits(turn.entries, result.edits)));
333
327
  const recent = recentStart(ctx, compactionSettings(model).keepRecentTokens);
334
328
  speculate(turn, leafId, recent, messages);
335
- if (result.tokens <= limit || !recent || failedEpoch === current)
336
- return undefined;
329
+ if (result.tokens <= limit || !recent || failedEpoch === current) return undefined;
337
330
  const writing = background.writing(current);
338
- if (writing && limit < piThreshold(model)) return "waiting" as const;
331
+ if (writing && result.tokens < piThreshold(model)) return "waiting" as const;
339
332
  return tryHandoff(turn, recent, writing ? undefined : messages);
340
333
  };
341
334
 
@@ -364,8 +357,7 @@ export default function contextKit(pi: ExtensionAPI): void {
364
357
  return compacted(turn.result, compaction);
365
358
  }
366
359
  } catch (error) {
367
- if (!signal.aborted)
368
- warn(ctx, error, "The next methods of the strategy are tried.");
360
+ if (!signal.aborted) warn(ctx, error, "The next methods of the strategy are tried.");
369
361
  }
370
362
  failedEpoch = current;
371
363
  return undefined;
@@ -397,16 +389,15 @@ export default function contextKit(pi: ExtensionAPI): void {
397
389
  return undefined;
398
390
  };
399
391
 
400
- pi.on("turn_end", async (event, ctx) => {
401
- const config = settings(ctx);
402
- if (!config.enabled) {
403
- showStatus(ctx, config);
404
- return undefined;
405
- }
392
+ const maintainTurn = async (
393
+ event: TurnEndEvent,
394
+ ctx: ExtensionContext,
395
+ config: ContextKitConfig,
396
+ ) => {
406
397
  const branch = ctx.sessionManager.getBranch();
407
398
  const current = epoch(branch);
408
399
  background.invalidate(current, branch);
409
- const model = ctx.model;
400
+ const model: Model<Api> | undefined = ctx.model;
410
401
  // Without a model the threshold is infinite, so maintenance plans no edits.
411
402
  if (!model) return undefined;
412
403
  const limit = threshold(model, config);
@@ -435,18 +426,32 @@ export default function contextKit(pi: ExtensionAPI): void {
435
426
  };
436
427
 
437
428
  // Try ordered strategies at Pi's threshold before its native hook can compact.
438
- const handed = before(methods, "handoff", "soft")
439
- ? await handoffAtTurn(turn)
440
- : undefined;
429
+ const handed = before(methods, "handoff", "soft") ? await handoffAtTurn(turn) : undefined;
441
430
  if (handed === "waiting") return persist(turn);
442
431
  if (handed) return handed;
443
- if (
444
- turn.result.tokens > limit &&
445
- !shakeFirst &&
446
- before(methods, "shake", "soft")
447
- )
432
+ if (turn.result.tokens > limit && !shakeFirst && before(methods, "shake", "soft"))
448
433
  turn.result = plan(true);
449
434
  return (await softAtTurn(turn)) ?? persist(turn);
435
+ };
436
+
437
+ pi.on("turn_end", async (event, ctx) => {
438
+ const config = settings(ctx);
439
+ if (!config.enabled || event.outcome === "aborted" || ctx.signal?.aborted) {
440
+ background.cancel();
441
+ showStatus(ctx, config);
442
+ return undefined;
443
+ }
444
+ if (
445
+ event.outcome === "error" ||
446
+ (event.message.role === "assistant" && event.message.stopReason === "length")
447
+ )
448
+ return undefined;
449
+ const result = await maintainTurn(event, ctx, config);
450
+ if (ctx.signal?.aborted) {
451
+ background.cancel();
452
+ return undefined;
453
+ }
454
+ return result;
450
455
  });
451
456
 
452
457
  const handoffBeforeCompact = async (
@@ -465,14 +470,11 @@ export default function contextKit(pi: ExtensionAPI): void {
465
470
  config,
466
471
  branch: branchEntries,
467
472
  // A focused /compact needs a note written for that focus.
468
- ready: customInstructions
469
- ? undefined
470
- : await background.takeReady(current, branchEntries),
473
+ ready: customInstructions ? undefined : await background.takeReady(current, branchEntries),
471
474
  keptEntryId: preparation.firstKeptEntryId,
472
475
  limit: Math.min(threshold(model, config), model.contextWindow),
473
476
  // The live context no longer fits the model after an overflow.
474
- messages:
475
- event.reason === "overflow" || writing ? undefined : liveMessages(ctx),
477
+ messages: event.reason === "overflow" || writing ? undefined : liveMessages(ctx),
476
478
  focus: customInstructions,
477
479
  signal: event.signal,
478
480
  cancelBackground: () => background.cancel(),
@@ -485,7 +487,7 @@ export default function contextKit(pi: ExtensionAPI): void {
485
487
  };
486
488
 
487
489
  pi.on("session_before_compact", async (event, ctx) => {
488
- const model = ctx.model;
490
+ const model: Model<Api> | undefined = ctx.model;
489
491
  const config = settings(ctx);
490
492
  if (!model || !handoffEnabled(config)) return undefined;
491
493
  const failed = failedEpoch === epoch(event.branchEntries);
@@ -493,8 +495,7 @@ export default function contextKit(pi: ExtensionAPI): void {
493
495
  try {
494
496
  return await handoffBeforeCompact(event, ctx, model, config);
495
497
  } catch (error) {
496
- if (!event.signal.aborted)
497
- warn(ctx, error, "Pi's summary is used instead.");
498
+ if (!event.signal.aborted) warn(ctx, error, "Pi's summary is used instead.");
498
499
  return undefined;
499
500
  }
500
501
  });
@@ -504,51 +505,61 @@ export default function contextKit(pi: ExtensionAPI): void {
504
505
  background.invalidate(epoch(branch), branch);
505
506
  showStatus(ctx);
506
507
  });
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",
508
+ /** One settings write per scope: an invalid option throws before any write. */
509
+ async function importOptions(manager: SettingsManager, item: SettingsImport): Promise<void> {
510
+ const patch = parseImported(item);
511
+ // `key` is read only by `inherit`, so any option name serves for `set`.
512
+ await contextKitSettings.writeSettings(
513
+ manager,
514
+ item.scope,
515
+ { action: "set", key: "enabled", patch },
516
+ () => true,
523
517
  );
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",
518
+ }
519
+
520
+ /** Imports each scope's context-kit.json or 0.3 block, unless that scope already has a namespace. */
521
+ async function migrate(ctx: ExtensionContext): Promise<void> {
522
+ const manager = layeredSettingsSession(ctx).settingsManager;
523
+ // Pi reports its own unreadable settings. The project import depends on the global one, so
524
+ // neither moves until Pi reads both.
525
+ if (manager.drainErrors().length > 0) return;
526
+ const { global, project } = paths(ctx);
527
+ try {
528
+ const imports = planSettingsImports(
529
+ scopeSource(manager.getGlobalSettings(), global),
530
+ project === undefined ? undefined : scopeSource(manager.getProjectSettings(), project),
546
531
  );
532
+ const renamed: string[] = [];
533
+ for (const item of imports) {
534
+ await importOptions(manager, item);
535
+ if (item.file) {
536
+ try {
537
+ renameSync(item.file, `${item.file}.migrated`);
538
+ } catch (error) {
539
+ ctx.ui.notify(
540
+ `pi-context-kit: settings were imported, but renaming ${item.file} failed (${errorText(error)}). The file stays in place and is not imported again.`,
541
+ "warning",
542
+ );
543
+ return;
544
+ }
545
+ renamed.push(`${item.file} was renamed to ${item.file}.migrated.`);
546
+ }
547
+ }
548
+ if (imports.length > 0)
549
+ ctx.ui.notify(
550
+ [
551
+ 'pi-context-kit moved its settings into Pi\'s settings.json under "context-kit". The 0.3 "contextKit" entry is no longer read.',
552
+ ...renamed,
553
+ ].join(" "),
554
+ "info",
555
+ );
556
+ } catch (error) {
557
+ warn(ctx, error, "Defaults apply until it works.", "moving settings");
547
558
  }
548
- };
559
+ }
549
560
 
550
- pi.on("session_start", (_event, ctx) => {
551
- migrate(ctx);
561
+ pi.on("session_start", async (_event, ctx) => {
562
+ await migrate(ctx);
552
563
  showStatus(ctx);
553
564
  });
554
565
  // A compaction returned from turn_end emits no session_compact.
@@ -562,70 +573,81 @@ export default function contextKit(pi: ExtensionAPI): void {
562
573
  statusContext = undefined;
563
574
  });
564
575
 
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
- }
576
+ /** Persists one change: the session's entries, or the scope's settings through Pi's backend. */
577
+ async function applyChange(
578
+ ctx: ExtensionContext,
579
+ scope: LayeredSettingScope,
580
+ change: ContextKitChange,
581
+ ): Promise<void> {
582
+ await contextKitSettings.writeChange(
583
+ pi,
584
+ layeredSettingsSession(ctx),
585
+ scope,
586
+ change,
587
+ () => true,
588
+ );
589
+ }
590
+
591
+ /** What the menu shows, read again after each change. */
592
+ const menuView = (ctx: ExtensionContext): ContextKitMenuView => {
593
+ const read = readSettingsOf(ctx);
594
+ return {
595
+ headline: [statusOf(ctx, read.config, liveTokens(ctx)) ?? "", ...read.problems],
596
+ scopes: layeredMenuScopes(read.manager),
597
+ // The strategy supplies the method order and background unless the scope sets them.
598
+ settings: {
599
+ ...read.lenient.settings,
600
+ background: read.config.background,
601
+ methodOrder: read.config.methodOrder,
602
+ },
603
+ sources: strategySources(read.lenient.sources),
604
+ authored: read.lenient.authored,
605
+ };
577
606
  };
578
607
 
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}`)}`;
608
+ /** An unset background or method order comes from the strategy, so it shows where that is set. */
609
+ const strategySources = (sources: Record<string, LayeredSettingSource>) => {
610
+ const derived = (key: string): LayeredSettingSource => {
611
+ const own = sources[key] ?? "default";
612
+ return own === "default" ? (sources.strategy ?? "default") : own;
613
+ };
614
+ return {
615
+ ...sources,
616
+ background: derived("background"),
617
+ methodOrder: derived("methodOrder"),
618
+ };
587
619
  };
588
620
 
589
- pi.registerCommand("context-kit", {
621
+ const menuHost = (ctx: ExtensionContext): ContextKitMenuHost => ({
622
+ view: () => menuView(ctx),
623
+ apply: async (scope, change) => {
624
+ await applyChange(ctx, scope, change);
625
+ showStatus(ctx);
626
+ },
627
+ });
628
+
629
+ registerSettingsCommand(pi, {
630
+ name: "context-kit",
590
631
  description: "Show and change pi-context-kit settings",
591
- handler: async (_args, ctx) => {
632
+ optionKeys: contextKitSettings.optionKeys,
633
+ parse: contextKitCommandSpec,
634
+ start(ctx) {
592
635
  // The settings warning points here, so it shows again.
593
636
  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
- });
637
+ return {
638
+ status: () => ctx.ui.notify(summaryText(settings(ctx)), "info"),
639
+ async menu() {
640
+ await ctx.ui.custom<void>(
641
+ (tui, theme, _keybindings, done) =>
642
+ new SettingsMenu(contextKitMenuSpec(menuHost(ctx)), { tui, theme }, () => done()),
643
+ );
644
+ },
645
+ async change(command) {
646
+ await applyChange(ctx, command.scope, command);
647
+ showStatus(ctx);
648
+ },
649
+ fail: (cause) => ctx.ui.notify(`pi-context-kit: ${errorText(cause)}`, "error"),
650
+ };
629
651
  },
630
652
  });
631
653
 
@@ -637,19 +659,12 @@ export default function contextKit(pi: ExtensionAPI): void {
637
659
  "Other branches are excluded. Images are represented only by MIME type. " +
638
660
  "Pass `query` to list matching entries with their IDs, newest first. Pass `entryId` to read one entry's text, with pagination for large entries.",
639
661
  parameters: Type.Object({
640
- query: Type.Optional(
641
- Type.String({ description: "Text to find, case-insensitive." }),
642
- ),
643
- regex: Type.Optional(
644
- Type.Boolean({ description: "Treat query as a regular expression." }),
645
- ),
646
- entryId: Type.Optional(
647
- Type.String({ description: "ID of the entry to read." }),
648
- ),
662
+ query: Type.Optional(Type.String({ description: "Text to find, case-insensitive." })),
663
+ regex: Type.Optional(Type.Boolean({ description: "Treat query as a regular expression." })),
664
+ entryId: Type.Optional(Type.String({ description: "ID of the entry to read." })),
649
665
  offset: Type.Optional(
650
666
  Type.Number({
651
- description:
652
- "Matches or characters to skip, as given in the previous result.",
667
+ description: "Matches or characters to skip, as given in the previous result.",
653
668
  }),
654
669
  ),
655
670
  limit: Type.Optional(
@@ -663,11 +678,7 @@ export default function contextKit(pi: ExtensionAPI): void {
663
678
  let text: string;
664
679
  if (params.entryId) text = readEntry(branch, params.entryId, params);
665
680
  else if (params.query)
666
- text = await searchEntries(
667
- branch,
668
- { ...params, query: params.query },
669
- signal,
670
- );
681
+ text = await searchEntries(branch, { ...params, query: params.query }, signal);
671
682
  else throw new Error("Pass query or entryId.");
672
683
  return { content: [{ type: "text", text }], details: undefined };
673
684
  },
@@ -693,25 +704,14 @@ function persisted(result: MaintenancePlan, limit: number) {
693
704
  : undefined;
694
705
  }
695
706
 
696
- function compacted(
697
- result: MaintenancePlan,
698
- compaction: Omit<CompactionEntryDraft, "type">,
699
- ) {
707
+ function compacted(result: MaintenancePlan, compaction: Omit<CompactionEntryDraft, "type">) {
700
708
  return {
701
- entries: [
702
- ...toDrafts(result.edits),
703
- { type: "compaction" as const, ...compaction },
704
- ],
709
+ entries: [...toDrafts(result.edits), { type: "compaction" as const, ...compaction }],
705
710
  };
706
711
  }
707
712
 
708
- function currentTokens(
709
- ctx: ExtensionContext,
710
- entries: readonly ProjectedSessionEntry[],
711
- ): number {
712
- return (
713
- ctx.getContextUsage()?.tokens ?? contextTokens(projectedMessages(entries))
714
- );
713
+ function currentTokens(ctx: ExtensionContext, entries: readonly ProjectedSessionEntry[]): number {
714
+ return ctx.getContextUsage()?.tokens ?? contextTokens(projectedMessages(entries));
715
715
  }
716
716
 
717
717
  function handoffEnabled(config: ContextKitConfig): boolean {
@@ -729,33 +729,21 @@ function liveMessages(ctx: ExtensionContext): Message[] {
729
729
  /** Tokens of the system prompt plus the projected context from `firstKeptEntryId` on. */
730
730
  function keptTokens(ctx: ExtensionContext, firstKeptEntryId: string): number {
731
731
  const entries = ctx.sessionManager.buildSessionProjection().entries;
732
- const start = entries.findIndex(
733
- (entry) => entry.sourceEntry.id === firstKeptEntryId,
734
- );
732
+ const start = entries.findIndex((entry) => entry.sourceEntry.id === firstKeptEntryId);
735
733
  if (start < 0) return Number.POSITIVE_INFINITY;
736
- const system = projectedMessages(entries)
737
- .filter((message) => message.role === "system")
738
- .at(-1);
734
+ const system = getCurrentSystemMessage(projectedMessages(entries));
739
735
  return contextTokens([
740
736
  ...(system ? [system] : []),
741
- ...projectedMessages(entries.slice(start)),
737
+ ...projectedMessages(entries.slice(start)).filter((message) => message.role !== "system"),
742
738
  ]);
743
739
  }
744
740
 
745
- function fits(
746
- summary: string,
747
- kept: number,
748
- limit: number,
749
- ratio: number,
750
- ): boolean {
741
+ function fits(summary: string, kept: number, limit: number, ratio: number): boolean {
751
742
  return Math.ceil(summary.length / 4) + kept <= limit * ratio;
752
743
  }
753
744
 
754
745
  /** Finds the retained boundary from model-visible entries, including prior compaction tails and edits. */
755
- function recentStart(
756
- ctx: ExtensionContext,
757
- keepRecentTokens: number,
758
- ): string | undefined {
746
+ function recentStart(ctx: ExtensionContext, keepRecentTokens: number): string | undefined {
759
747
  const entries: SessionEntry[] = [];
760
748
  for (const projected of ctx.sessionManager.buildSessionProjection().entries) {
761
749
  const source = projected.sourceEntry;
@@ -774,3 +762,38 @@ function recentStart(
774
762
  const cut = findCutPoint(entries, 0, entries.length, keepRecentTokens);
775
763
  return entries[cut.firstKeptEntryIndex]?.id;
776
764
  }
765
+
766
+ /** The scope's document with its `context-kit` namespace, and its file when that file exists. */
767
+ function scopeSource(document: object, path: string): ScopeSource {
768
+ const source: ScopeSource = {
769
+ stored: Reflect.get(document, "context-kit") !== undefined,
770
+ legacy: Reflect.get(document, "contextKit"),
771
+ };
772
+ return existsSync(path) ? { ...source, file: { path, content: readSettingsFile(path) } } : source;
773
+ }
774
+
775
+ /** Validates an import's options; an error names the `context-kit.json` they come from. */
776
+ function parseImported(item: SettingsImport): ContextKitOptionsPatch {
777
+ try {
778
+ return contextKitSettings.parseOptions(item.options, item.scope);
779
+ } catch (error) {
780
+ if (!item.file) throw error;
781
+ const message = errorText(error);
782
+ throw new Error(`${item.file} is invalid (${message})`, { cause: error });
783
+ }
784
+ }
785
+
786
+ /** One-line status for modes without the settings menu. */
787
+ function summaryText(config: ContextKitConfig): string {
788
+ if (!config.enabled) return "pi-context-kit: automatic cleanup off. Settings: /context-kit";
789
+ const at =
790
+ config.threshold === "pi"
791
+ ? "Pi's limit"
792
+ : "tokens" in config.threshold
793
+ ? `${config.threshold.tokens} tokens`
794
+ : `${config.threshold.percent}%`;
795
+ const method = config.customOrder
796
+ ? `custom methods (${config.methodOrder.join(", ") || "none"})`
797
+ : config.strategy;
798
+ return `pi-context-kit: automatic cleanup at ${at}, with ${method}. Settings: /context-kit`;
799
+ }