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
package/src/menu.ts ADDED
@@ -0,0 +1,159 @@
1
+ import type { LayeredSettingScope, LayeredSettingSource } from "pi-hl-utils/layered-settings";
2
+ import {
3
+ effectiveWithSource,
4
+ type SettingRow,
5
+ type SettingsMenuSpec,
6
+ } from "pi-hl-utils/settings-menu";
7
+
8
+ import {
9
+ type ContextKitChange,
10
+ type ContextKitOptions,
11
+ type ContextKitOptionsPatch,
12
+ contextKitSettings,
13
+ } from "./context-kit-settings.ts";
14
+
15
+ type OptionKey = keyof ContextKitOptionsPatch;
16
+
17
+ /** What the menu displays, read again after each change. */
18
+ export interface ContextKitMenuView {
19
+ headline: readonly string[];
20
+ /** Writable scopes; `project` only when the project is trusted. */
21
+ scopes: readonly LayeredSettingScope[];
22
+ /** Effective options after scope precedence. */
23
+ settings: ContextKitOptions;
24
+ sources: Readonly<Partial<Record<OptionKey, LayeredSettingSource>>>;
25
+ /** Options that each scope authors itself. */
26
+ authored: Readonly<Partial<Record<LayeredSettingScope, ContextKitOptionsPatch>>>;
27
+ }
28
+
29
+ /** The extension side of the menu: reads the view and applies one change. */
30
+ export interface ContextKitMenuHost {
31
+ view(): ContextKitMenuView;
32
+ /** Validates, persists, and applies one change; a rejection shows inline in the menu. */
33
+ apply(scope: LayeredSettingScope, change: ContextKitChange): Promise<void>;
34
+ }
35
+
36
+ const onOffKeys = new Set<OptionKey>(["enabled", "background", "supersedeReads", "pruneEnabled"]);
37
+ const strategyValues = ["balanced", "frugal", "pi-summary"] as const;
38
+
39
+ const descriptions = {
40
+ enabled:
41
+ "Makes room in a long conversation so the agent keeps working. Off leaves only Pi's own cleanup.",
42
+ threshold:
43
+ "Where cleanup starts: a token count, a percentage such as 75% of each window, or pi for Pi's own limit.",
44
+ strategy:
45
+ "balanced writes notes ahead of time. frugal shortens old outputs without a model call. pi-summary uses Pi's own summary.",
46
+ methodOrder:
47
+ "What to try, in order, when the context stays above the threshold after pruning. Overrides strategy.",
48
+ background: "Writes the handoff note in the background, before the threshold.",
49
+ supersedeReads: "Replaces the old copy of a file that the model read again.",
50
+ progressRatio:
51
+ "Each method must bring the context to this fraction of the threshold, or the next method runs.",
52
+ pruneEnabled: "Clears old tool outputs and file reads from the context.",
53
+ pruneProtectTokens: "Recent tokens that pruning leaves as they are.",
54
+ pruneMinSavings: "Pruning runs only when it saves at least this many tokens.",
55
+ pruneMinTokens: "Outputs smaller than this many tokens are never pruned.",
56
+ shakeProtectTokens: "Recent tokens that shaking leaves as they are.",
57
+ shakeMinSavings: "Shaking runs only when it saves at least this many tokens.",
58
+ shakeBlockMinTokens: "Blocks smaller than this many tokens are never elided.",
59
+ } satisfies Record<OptionKey, string>;
60
+
61
+ const hints: Partial<Record<OptionKey, string>> = {
62
+ threshold: "a token count, a percentage such as 75%, pi, or inherit",
63
+ strategy: "balanced, frugal, pi-summary, or inherit",
64
+ methodOrder: "handoff, shake and soft, comma-separated, or inherit",
65
+ progressRatio: "a number above 0, up to 1, or inherit",
66
+ };
67
+
68
+ /** Display text of an option value; an unset value reads as inherit. */
69
+ function valueText(value: unknown): string {
70
+ if (value === undefined) return "inherit";
71
+ if (Array.isArray(value)) return value.join(", ");
72
+ if (typeof value === "boolean") return value ? "on" : "off";
73
+ if (typeof value === "number" || typeof value === "string") return String(value);
74
+ throw new Error(`Unexpected option value: ${JSON.stringify(value)}`);
75
+ }
76
+
77
+ /** The JSON value that menu text stands for; the option schema validates it before any write. */
78
+ function menuValue(key: OptionKey, text: string): unknown {
79
+ if (onOffKeys.has(key)) return text === "on" ? true : text === "off" ? false : text;
80
+ if (key === "threshold" && /^\d+$/.test(text)) return Number(text);
81
+ if (key === "methodOrder") return text.split(",").map((method) => method.trim());
82
+ if (key === "strategy" || key === "threshold") return text;
83
+ return Number(text);
84
+ }
85
+
86
+ /** One change typed or chosen in the menu for one scope. */
87
+ export function menuChange(
88
+ key: string,
89
+ text: string,
90
+ scope: LayeredSettingScope,
91
+ ): ContextKitChange {
92
+ const optionKey = contextKitSettings.optionKey(key);
93
+ const value = text.trim();
94
+ if (value === "inherit") return { action: "inherit", key: optionKey };
95
+ if (value === "") throw new Error(`Enter a value for ${optionKey}, or inherit`);
96
+ return {
97
+ action: "set",
98
+ key: optionKey,
99
+ patch: contextKitSettings.parseOptions({ [optionKey]: menuValue(optionKey, value) }, scope),
100
+ };
101
+ }
102
+
103
+ /** Values a cycled row steps through; `inherit` removes the scope's own value. */
104
+ function cycleValues(key: OptionKey): readonly string[] {
105
+ if (key === "strategy") return ["inherit", ...strategyValues];
106
+ return ["inherit", "on", "off"];
107
+ }
108
+
109
+ function isCycleKey(key: OptionKey): boolean {
110
+ return key === "strategy" || onOffKeys.has(key);
111
+ }
112
+
113
+ function optionRow(
114
+ view: ContextKitMenuView,
115
+ scope: LayeredSettingScope,
116
+ id: string,
117
+ ): SettingRow<ContextKitChange> {
118
+ const key = contextKitSettings.optionKey(id);
119
+ const source = view.sources[key] ?? "default";
120
+ const fields = {
121
+ id: key,
122
+ label: source === "default" ? key : `${key} [${source}]`,
123
+ description: descriptions[key],
124
+ };
125
+ if (isCycleKey(key)) {
126
+ const own = view.authored[scope]?.[key];
127
+ return {
128
+ kind: "cycle",
129
+ ...fields,
130
+ values: cycleValues(key),
131
+ own: own === undefined ? undefined : valueText(own),
132
+ inEffect: effectiveWithSource(valueText(view.settings[key]), source),
133
+ source,
134
+ change: (value, scope) => menuChange(key, value, scope),
135
+ };
136
+ }
137
+ return {
138
+ kind: "input",
139
+ ...fields,
140
+ value: valueText(view.settings[key]),
141
+ hint: hints[key] ?? "a whole number, 0 or more, or inherit",
142
+ change: (text, scope) => menuChange(key, text, scope),
143
+ };
144
+ }
145
+
146
+ /** The `/context-kit` settings menu: a Scope row, then one row per option. */
147
+ export function contextKitMenuSpec(
148
+ host: ContextKitMenuHost,
149
+ ): SettingsMenuSpec<ContextKitMenuView, ContextKitChange> {
150
+ return {
151
+ title: "Context cleanup settings",
152
+ read: () => host.view(),
153
+ rows: (view, scope) => [
154
+ { kind: "scope" },
155
+ ...contextKitSettings.optionKeys.map((id) => optionRow(view, scope, id)),
156
+ ],
157
+ apply: (scope, change) => host.apply(scope, change),
158
+ };
159
+ }
package/src/migrate.ts CHANGED
@@ -1,6 +1,7 @@
1
+ import { isRecord } from "pi-hl-utils/record";
2
+
1
3
  import {
2
4
  isMethod,
3
- isRecord,
4
5
  isStrategy,
5
6
  type Method,
6
7
  STRATEGIES,
@@ -14,6 +15,97 @@ const NAMES = Object.keys(STRATEGIES).filter(isStrategy);
14
15
  /** Keys 0.3 had at the top level that 0.4 keeps under `advanced`, unchanged. */
15
16
  const ADVANCED = ["supersedeReads", "progressRatio", "prune", "shake"];
16
17
 
18
+ /** What one scope has before the import: its namespace, its 0.4 file and its 0.3 block. */
19
+ export interface ScopeSource {
20
+ /** Whether Pi's settings document of this scope already has the `context-kit` namespace. */
21
+ stored: boolean;
22
+ /** The scope's `context-kit.json`, when that file exists. */
23
+ file?: { path: string; content: Record<string, unknown> };
24
+ /** The 0.3 `contextKit` block of Pi's settings document, when it has one. */
25
+ legacy?: unknown;
26
+ }
27
+
28
+ /** Flat options to write to one scope's `context-kit` namespace, and the file they come from. */
29
+ export interface SettingsImport {
30
+ scope: "global" | "project";
31
+ options: Record<string, unknown>;
32
+ /** Renamed to `.migrated` after the options are written. */
33
+ file?: string;
34
+ }
35
+
36
+ /**
37
+ * Plans the import of each scope that has no `context-kit` namespace yet. A scope imports its
38
+ * `context-kit.json` when that file exists, else its 0.3 block. The project block converts over
39
+ * the global settings as they are after this import, as 0.3 merged them.
40
+ */
41
+ export function planSettingsImports(
42
+ global: ScopeSource,
43
+ project: ScopeSource | undefined,
44
+ ): SettingsImport[] {
45
+ const globalNested = nestedGlobal(global);
46
+ const imports: SettingsImport[] = [];
47
+ const globalImport = importOf("global", global, () => globalNested);
48
+ if (globalImport) imports.push(globalImport);
49
+ if (project) {
50
+ const projectImport = importOf("project", project, () =>
51
+ migrateProject(global.legacy ?? {}, project.legacy, globalNested),
52
+ );
53
+ if (projectImport) imports.push(projectImport);
54
+ }
55
+ return imports;
56
+ }
57
+
58
+ function nestedGlobal(global: ScopeSource): Record<string, unknown> {
59
+ if (global.file) return global.file.content;
60
+ return global.legacy === undefined ? {} : migrateLegacy(global.legacy);
61
+ }
62
+
63
+ function importOf(
64
+ scope: SettingsImport["scope"],
65
+ source: ScopeSource,
66
+ legacyNested: () => Record<string, unknown>,
67
+ ): SettingsImport | undefined {
68
+ if (source.stored) return undefined;
69
+ if (source.file)
70
+ return {
71
+ scope,
72
+ options: flattenSettings(source.file.content),
73
+ file: source.file.path,
74
+ };
75
+ if (source.legacy === undefined) return undefined;
76
+ return { scope, options: flattenSettings(legacyNested()) };
77
+ }
78
+
79
+ /**
80
+ * Converts 0.4 nested options, as `context-kit.json` and the 0.3 conversion write them, to the
81
+ * flat keys of the `context-kit` namespace. A nested key with an unknown name keeps its name, so
82
+ * the option schema rejects it.
83
+ */
84
+ export function flattenSettings(nested: Record<string, unknown>): Record<string, unknown> {
85
+ const { $schema: _schema, advanced, ...flat } = nested;
86
+ if (advanced === undefined) return flat;
87
+ if (!isRecord(advanced)) return { ...flat, advanced };
88
+ const { prune, shake, ...options } = advanced;
89
+ return {
90
+ ...flat,
91
+ ...options,
92
+ ...prefixed("prune", prune),
93
+ ...prefixed("shake", shake),
94
+ };
95
+ }
96
+
97
+ /** `{ enabled }` under `prune` becomes `{ pruneEnabled }`; a value that is not an object is kept as it is. */
98
+ function prefixed(prefix: string, value: unknown): Record<string, unknown> {
99
+ if (value === undefined) return {};
100
+ if (!isRecord(value)) return { [prefix]: value };
101
+ return Object.fromEntries(
102
+ Object.entries(value).map(([key, option]) => [
103
+ prefix + key.charAt(0).toUpperCase() + key.slice(1),
104
+ option,
105
+ ]),
106
+ );
107
+ }
108
+
17
109
  /**
18
110
  * Converts the 0.3 `contextKit` block of Pi's settings into the content of `context-kit.json`
19
111
  * with the same behavior. An invalid threshold or method order is dropped, so its default applies,
@@ -28,10 +120,7 @@ export function migrateLegacy(legacy: unknown): Record<string, unknown> {
28
120
  const { strategy, order, background } = methods(old);
29
121
  if (strategy && strategy !== "balanced") result.strategy = strategy;
30
122
  if (!strategy) advanced.methodOrder = order;
31
- if (
32
- writesHandoff(order) &&
33
- background !== STRATEGIES[strategy ?? "balanced"].background
34
- )
123
+ if (writesHandoff(order) && background !== STRATEGIES[strategy ?? "balanced"].background)
35
124
  advanced.background = background;
36
125
  return withAdvanced(result, advanced);
37
126
  }
@@ -47,10 +136,7 @@ export function migrateProject(
47
136
  globalFile: Record<string, unknown>,
48
137
  ): Record<string, unknown> {
49
138
  const project = isRecord(projectLegacy) ? projectLegacy : {};
50
- const merged = mergeSettings(
51
- isRecord(globalLegacy) ? globalLegacy : {},
52
- project,
53
- );
139
+ const merged = mergeSettings(isRecord(globalLegacy) ? globalLegacy : {}, project);
54
140
  const result: Record<string, unknown> = {};
55
141
  if (typeof project.enabled === "boolean") result.enabled = project.enabled;
56
142
  if ("thresholdTokens" in project || "thresholdPercent" in project)
@@ -70,15 +156,12 @@ function projectMethods(
70
156
  globalFile: Record<string, unknown>,
71
157
  ): { strategy?: Strategy; advanced: Record<string, unknown> } {
72
158
  const { strategy, order, background } = methods(merged);
73
- const globalAdvanced = isRecord(globalFile.advanced)
74
- ? globalFile.advanced
75
- : {};
159
+ const globalAdvanced = isRecord(globalFile.advanced) ? globalFile.advanced : {};
76
160
  const advanced: Record<string, unknown> = {};
77
161
  // false avoids the "no effect" warning for a global background that this order does not use.
78
162
  if (writesHandoff(order) || "background" in globalAdvanced)
79
163
  advanced.background = writesHandoff(order) && background;
80
- if (strategy && !("methodOrder" in globalAdvanced))
81
- return { strategy, advanced };
164
+ if (strategy && !("methodOrder" in globalAdvanced)) return { strategy, advanced };
82
165
  return { advanced: { methodOrder: order, ...advanced } };
83
166
  }
84
167
 
@@ -114,8 +197,7 @@ function threshold(old: Record<string, unknown>): number | string {
114
197
  const tokens = old.thresholdTokens;
115
198
  if (Number.isSafeInteger(tokens) && Number(tokens) > 0) return Number(tokens);
116
199
  const percent = old.thresholdPercent;
117
- if (typeof percent === "number" && percent > 0 && percent <= 100)
118
- return `${percent}%`;
200
+ if (typeof percent === "number" && percent > 0 && percent <= 100) return `${percent}%`;
119
201
  return "pi";
120
202
  }
121
203
 
@@ -129,7 +211,5 @@ function methodOrder(value: unknown): Method[] {
129
211
  }
130
212
 
131
213
  function same(a: readonly Method[], b: readonly Method[]): boolean {
132
- return (
133
- a.length === b.length && a.every((method, index) => method === b[index])
134
- );
214
+ return a.length === b.length && a.every((method, index) => method === b[index]);
135
215
  }
package/src/note.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import type { Api, Message, Model, ThinkingLevel } from "@earendil-works/pi-ai";
2
2
  import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
3
+
3
4
  import type { Note } from "./background.ts";
4
5
  import { handoffContext, handoffNote } from "./handoff.ts";
5
6
 
@@ -11,19 +12,17 @@ export interface NoteRequest {
11
12
  messages: readonly Message[];
12
13
  /** The session's level: Anthropic drops the cached messages when thinking differs. */
13
14
  reasoning: ThinkingLevel | undefined;
14
- focus?: string;
15
+ focus?: string | undefined;
15
16
  signal: AbortSignal;
16
- maxTokens?: number;
17
+ maxTokens: number;
17
18
  }
18
19
 
19
20
  /** Sends the turn's tool_choice too: Anthropic drops the cached messages when it differs. */
20
- export async function requestNote(
21
- request: NoteRequest,
22
- ): Promise<Note | undefined> {
21
+ export async function requestNote(request: NoteRequest): Promise<Note | undefined> {
23
22
  const context = handoffContext(request.messages, request.focus);
24
23
  const response = await request.registry
25
24
  .streamSimple(request.model, context, {
26
- reasoning: request.reasoning,
25
+ ...(request.reasoning === undefined ? {} : { reasoning: request.reasoning }),
27
26
  maxTokens: request.maxTokens,
28
27
  signal: request.signal,
29
28
  sessionId: request.sessionId,
package/src/prune.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import type { ProjectedSessionEntry } from "@earendil-works/pi-coding-agent";
2
+
2
3
  import { type Edit, messageTokens, withContent } from "./context.ts";
3
4
  import { newestToolResults, type ToolResult } from "./tool-calls.ts";
4
5
 
@@ -38,7 +39,7 @@ export function pruneToolOutputs(
38
39
  savings += edit.saved;
39
40
  edits.push(edit.edit);
40
41
  }
41
- return savings >= options.minSavings ? edits.reverse() : [];
42
+ return savings >= options.minSavings ? edits.toReversed() : [];
42
43
  }
43
44
 
44
45
  function pruneEdit(
package/src/recall.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import { Worker } from "node:worker_threads";
2
+
2
3
  import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
3
4
  import type { SessionEntry } from "@earendil-works/pi-coding-agent";
4
5
 
@@ -21,8 +22,7 @@ const DEFAULT_CHARS = 20_000;
21
22
  const SNIPPET_CHARS = 160;
22
23
  const REGEX_DEADLINE_MS = 500;
23
24
 
24
- type RegexWorkerResult =
25
- { type: "success"; indexes: number[] } | { type: "error"; error: string };
25
+ type RegexWorkerResult = { type: "success"; indexes: number[] } | { type: "error"; error: string };
26
26
 
27
27
  /** Searches the raw text of every entry on the branch, including compacted and edited ones. */
28
28
  export async function searchEntries(
@@ -40,25 +40,20 @@ export async function searchEntries(
40
40
  options.query,
41
41
  signal,
42
42
  )
43
- : indexed.map(({ text }) =>
44
- text.toLowerCase().indexOf(options.query.toLowerCase()),
45
- );
43
+ : indexed.map(({ text }) => text.toLowerCase().indexOf(options.query.toLowerCase()));
46
44
  const hits: string[] = [];
47
45
  for (let i = indexed.length - 1; i >= 0; i--) {
48
46
  const item = indexed[i];
49
47
  const index = indexes[i];
50
48
  if (item && index !== undefined && index >= 0)
51
- hits.push(
52
- `${item.entry.id} ${entryLabel(item.entry)}: ${snippet(item.text, index)}`,
53
- );
49
+ hits.push(`${item.entry.id} ${entryLabel(item.entry)}: ${snippet(item.text, index)}`);
54
50
  }
55
51
  if (hits.length === 0) return "No entries match.";
56
52
  const offset = clamp(options.offset, 0, hits.length, 0);
57
53
  const limit = clamp(options.limit, 1, MAX_RESULTS, DEFAULT_RESULTS);
58
54
  const page = hits.slice(offset, offset + limit);
59
55
  const end = offset + page.length;
60
- if (end < hits.length)
61
- page.push(`[${hits.length} matches. Use offset=${end} for more.]`);
56
+ if (end < hits.length) page.push(`[${hits.length} matches. Use offset=${end} for more.]`);
62
57
  return page.join("\n");
63
58
  }
64
59
 
@@ -112,11 +107,7 @@ function regexIndexes(
112
107
  const onAbort = () => finish(() => reject(new Error("Search aborted.")));
113
108
  const timer = setTimeout(
114
109
  () =>
115
- finish(() =>
116
- reject(
117
- new Error(`Regex search exceeded ${REGEX_DEADLINE_MS}ms deadline.`),
118
- ),
119
- ),
110
+ finish(() => reject(new Error(`Regex search exceeded ${REGEX_DEADLINE_MS}ms deadline.`))),
120
111
  REGEX_DEADLINE_MS,
121
112
  );
122
113
  signal?.addEventListener("abort", onAbort, { once: true });
@@ -127,10 +118,7 @@ function regexIndexes(
127
118
  });
128
119
  worker.once("error", (error) => finish(() => reject(error)));
129
120
  worker.once("exit", (code) => {
130
- if (code !== 0)
131
- finish(() =>
132
- reject(new Error(`Regex worker exited with code ${code}.`)),
133
- );
121
+ if (code !== 0) finish(() => reject(new Error(`Regex worker exited with code ${code}.`)));
134
122
  });
135
123
  });
136
124
  }
@@ -138,9 +126,7 @@ function regexIndexes(
138
126
  function entryLabel(entry: SessionEntry): string {
139
127
  if (entry.type !== "message") return entry.type;
140
128
  const { message } = entry;
141
- return message.role === "toolResult"
142
- ? `toolResult ${message.toolName}`
143
- : message.role;
129
+ return message.role === "toolResult" ? `toolResult ${message.toolName}` : message.role;
144
130
  }
145
131
 
146
132
  function entryText(entry: SessionEntry): string {
@@ -157,9 +143,7 @@ function entryText(entry: SessionEntry): string {
157
143
  }
158
144
  }
159
145
 
160
- function messageText(
161
- message: Extract<SessionEntry, { type: "message" }>["message"],
162
- ): string {
146
+ function messageText(message: Extract<SessionEntry, { type: "message" }>["message"]): string {
163
147
  switch (message.role) {
164
148
  case "user":
165
149
  case "custom":
@@ -176,19 +160,17 @@ function messageText(
176
160
  return `[${message.toolName} result${message.isError ? " error" : ""}]\n${contentText(message.content)}`;
177
161
  case "system":
178
162
  return "";
163
+ case "bashExecution":
164
+ return message.excludeFromContext ? "" : JSON.stringify(message);
179
165
  default:
180
166
  return JSON.stringify(message);
181
167
  }
182
168
  }
183
169
 
184
- function contentText(
185
- content: string | readonly (TextContent | ImageContent)[],
186
- ): string {
170
+ function contentText(content: string | readonly (TextContent | ImageContent)[]): string {
187
171
  if (typeof content === "string") return content;
188
172
  return content
189
- .map((block) =>
190
- block.type === "text" ? block.text : `[image ${block.mimeType}]`,
191
- )
173
+ .map((block) => (block.type === "text" ? block.text : `[image ${block.mimeType}]`))
192
174
  .join("\n");
193
175
  }
194
176
 
@@ -201,12 +183,7 @@ function snippet(text: string, index: number): string {
201
183
  return `${start > 0 ? "…" : ""}${flat}${start + SNIPPET_CHARS < text.length ? "…" : ""}`;
202
184
  }
203
185
 
204
- function clamp(
205
- value: number | undefined,
206
- min: number,
207
- max: number,
208
- fallback: number,
209
- ): number {
186
+ function clamp(value: number | undefined, min: number, max: number, fallback: number): number {
210
187
  if (value === undefined || !Number.isFinite(value)) return fallback;
211
188
  return Math.min(max, Math.max(min, Math.floor(value)));
212
189
  }
@@ -1,17 +1,8 @@
1
- import {
2
- chmodSync,
3
- existsSync,
4
- linkSync,
5
- mkdirSync,
6
- readFileSync,
7
- realpathSync,
8
- renameSync,
9
- rmSync,
10
- statSync,
11
- writeFileSync,
12
- } from "node:fs";
13
- import { dirname, join } from "node:path";
14
- import { isRecord } from "./config.ts";
1
+ import { readFileSync } from "node:fs";
2
+ import { join } from "node:path";
3
+
4
+ import { errorText } from "pi-hl-utils/errors";
5
+ import { isRecord } from "pi-hl-utils/record";
15
6
 
16
7
  const FILE_NAME = "context-kit.json";
17
8
 
@@ -21,89 +12,13 @@ export interface SettingsPaths {
21
12
  project: string | undefined;
22
13
  }
23
14
 
24
- export function settingsPaths(
25
- agentDir: string,
26
- cwd: string,
27
- trusted: boolean,
28
- ): SettingsPaths {
15
+ export function settingsPaths(agentDir: string, cwd: string, trusted: boolean): SettingsPaths {
29
16
  return {
30
17
  global: join(agentDir, FILE_NAME),
31
18
  project: trusted ? join(cwd, ".pi", FILE_NAME) : undefined,
32
19
  };
33
20
  }
34
21
 
35
- /** Merges the global and project files. A file that cannot be read is reported and ignored. */
36
- export function loadSettings(paths: SettingsPaths): {
37
- raw: Record<string, unknown>;
38
- problems: string[];
39
- } {
40
- const problems: string[] = [];
41
- let raw: Record<string, unknown> = {};
42
- for (const path of [paths.global, paths.project]) {
43
- if (!path) continue;
44
- try {
45
- raw = mergeSettings(raw, readSettingsFile(path));
46
- } catch (error) {
47
- problems.push(`${errorMessage(error)}, file ignored`);
48
- }
49
- }
50
- return { raw, problems };
51
- }
52
-
53
- /** Sets one top-level key and keeps the rest of the file. The file is replaced atomically. */
54
- export function updateSetting(path: string, key: string, value: unknown) {
55
- const next = { ...readSettingsFile(path), [key]: value };
56
- // The rename replaces the target, so a symbolic link, for example to dotfiles, stays.
57
- const target = existsSync(path) ? realpathSync(path) : path;
58
- mkdirSync(dirname(target), { recursive: true });
59
- const temporary = `${target}.${process.pid}.tmp`;
60
- try {
61
- writeFileSync(temporary, `${JSON.stringify(next, null, 2)}\n`);
62
- if (existsSync(target)) chmodSync(temporary, statSync(target).mode);
63
- renameSync(temporary, target);
64
- } finally {
65
- rmSync(temporary, { force: true });
66
- }
67
- }
68
-
69
- /** Creates the file with this content. Returns false when the file exists, which it keeps. */
70
- export function createSettings(
71
- path: string,
72
- content: Record<string, unknown>,
73
- ): boolean {
74
- mkdirSync(dirname(path), { recursive: true });
75
- const temporary = `${path}.${process.pid}.tmp`;
76
- try {
77
- writeFileSync(temporary, `${JSON.stringify(content, null, 2)}\n`);
78
- // The link appears complete or not at all, and fails when the file exists, so two Pi
79
- // processes cannot both create it.
80
- linkSync(temporary, path);
81
- return true;
82
- } catch (error) {
83
- if (isRecord(error) && error.code === "EEXIST") return false;
84
- throw error;
85
- } finally {
86
- rmSync(temporary, { force: true });
87
- }
88
- }
89
-
90
- /**
91
- * Writes the key where it takes effect: the project file when that file sets it, otherwise the
92
- * global file. Returns the path written.
93
- */
94
- export function saveSetting(
95
- paths: SettingsPaths,
96
- key: string,
97
- value: unknown,
98
- ): string {
99
- const path =
100
- paths.project && readSettingsFile(paths.project)[key] !== undefined
101
- ? paths.project
102
- : paths.global;
103
- updateSetting(path, key, value);
104
- return path;
105
- }
106
-
107
22
  /** The content of one settings file, `{}` when it does not exist. Throws when it is not a JSON object. */
108
23
  export function readSettingsFile(path: string): Record<string, unknown> {
109
24
  let text: string;
@@ -111,13 +26,17 @@ export function readSettingsFile(path: string): Record<string, unknown> {
111
26
  text = readFileSync(path, "utf8");
112
27
  } catch (error) {
113
28
  if (isRecord(error) && error.code === "ENOENT") return {};
114
- throw new Error(`${path} cannot be read (${errorMessage(error)})`);
29
+ throw new Error(`${path} cannot be read (${errorText(error)})`, {
30
+ cause: error,
31
+ });
115
32
  }
116
33
  let value: unknown;
117
34
  try {
118
35
  value = JSON.parse(text);
119
36
  } catch (error) {
120
- throw new Error(`${path} is not valid JSON (${errorMessage(error)})`);
37
+ throw new Error(`${path} is not valid JSON (${errorText(error)})`, {
38
+ cause: error,
39
+ });
121
40
  }
122
41
  if (!isRecord(value)) throw new Error(`${path} must contain a JSON object`);
123
42
  return value;
@@ -136,10 +55,7 @@ export function mergeSettings(
136
55
  const current = result[key];
137
56
  // A plain assignment of "__proto__" would set the prototype instead of a key.
138
57
  Object.defineProperty(result, key, {
139
- value:
140
- isRecord(current) && isRecord(value)
141
- ? mergeSettings(current, value)
142
- : value,
58
+ value: isRecord(current) && isRecord(value) ? mergeSettings(current, value) : value,
143
59
  enumerable: true,
144
60
  writable: true,
145
61
  configurable: true,
@@ -147,7 +63,3 @@ export function mergeSettings(
147
63
  }
148
64
  return result;
149
65
  }
150
-
151
- function errorMessage(error: unknown): string {
152
- return error instanceof Error ? error.message : String(error);
153
- }