@mrclrchtr/supi-context 12.0.0 → 14.0.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 +4 -0
- package/node_modules/@mrclrchtr/supi-core/package.json +3 -1
- package/node_modules/@mrclrchtr/supi-core/src/api.ts +4 -0
- package/node_modules/@mrclrchtr/supi-core/src/context/context-tag.ts +1 -1
- package/node_modules/@mrclrchtr/supi-core/src/debug-registry.ts +78 -13
- package/node_modules/@mrclrchtr/supi-core/src/footer-registry.ts +41 -9
- package/node_modules/@mrclrchtr/supi-core/src/retired-packages.ts +152 -0
- package/node_modules/@mrclrchtr/supi-core/src/session.ts +3 -0
- package/node_modules/@mrclrchtr/supi-core/src/shell-hints.ts +46 -0
- package/node_modules/@mrclrchtr/supi-core/src/side-run.ts +46 -0
- package/node_modules/@mrclrchtr/supi-core/src/spill.ts +93 -0
- package/package.json +2 -2
- package/src/tool/context_report/result.ts +6 -6
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,9 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [13.0.0]
|
|
4
|
+
|
|
5
|
+
- Oversized `context_report` attribution files are now written to one private per-user directory, `$TMPDIR/supi-<uid>/`, instead of a new `supi-*` directory per call. Identical content reuses one file. SuPi never deletes these files; the OS temp purge does ([#597](https://github.com/mrclrchtr/supi/issues/597)).
|
|
6
|
+
|
|
3
7
|
## [12.0.0]
|
|
4
8
|
|
|
5
9
|
- Codemode now lists the `context_report` tool under a `context` namespace heading, so scripts can find them with `describeNamespace("context")` or `searchTools(query, { namespace: "context" })`. It is annotated read-only ([#582](https://github.com/mrclrchtr/supi/issues/582)).
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mrclrchtr/supi-core",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "14.0.0",
|
|
4
4
|
"description": "Shared settings, configuration, reporting, and session infrastructure",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -63,8 +63,10 @@
|
|
|
63
63
|
"./project": "./src/project.ts",
|
|
64
64
|
"./prompt-surface": "./src/prompt-surface.ts",
|
|
65
65
|
"./report": "./src/report.ts",
|
|
66
|
+
"./retired-packages": "./src/retired-packages.ts",
|
|
66
67
|
"./session": "./src/session.ts",
|
|
67
68
|
"./settings": "./src/settings.ts",
|
|
69
|
+
"./spill": "./src/spill.ts",
|
|
68
70
|
"./spinner-frames": "./src/spinner-frames.ts",
|
|
69
71
|
"./status-spinner": "./src/status-spinner.ts",
|
|
70
72
|
"./terminal": "./src/terminal.ts",
|
|
@@ -29,10 +29,14 @@ export * from "./prompt-surface.ts";
|
|
|
29
29
|
// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
|
|
30
30
|
export * from "./report.ts";
|
|
31
31
|
// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
|
|
32
|
+
export * from "./retired-packages.ts";
|
|
33
|
+
// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
|
|
32
34
|
export * from "./session.ts";
|
|
33
35
|
// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
|
|
34
36
|
export * from "./settings.ts";
|
|
35
37
|
// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
|
|
38
|
+
export * from "./spill.ts";
|
|
39
|
+
// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
|
|
36
40
|
export * from "./spinner-frames.ts";
|
|
37
41
|
// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
|
|
38
42
|
export * from "./status-spinner.ts";
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
/**
|
|
9
9
|
* Wrap content in an `<extension-context>` XML tag.
|
|
10
10
|
*
|
|
11
|
-
* @param source - Extension identifier (e.g. "supi-
|
|
11
|
+
* @param source - Extension identifier (e.g. "supi-lsp")
|
|
12
12
|
* @param content - The text content to wrap
|
|
13
13
|
* @param attrs - Optional additional attributes (rendered as key="value")
|
|
14
14
|
* @returns Formatted XML string
|
|
@@ -16,8 +16,17 @@ export interface DebugRegistryConfig {
|
|
|
16
16
|
agentAccess: DebugAgentAccess;
|
|
17
17
|
/** Whether Agent Run retrospective capture is explicitly enabled. */
|
|
18
18
|
agentRunRetrospectivesEnabled: boolean;
|
|
19
|
-
/**
|
|
19
|
+
/**
|
|
20
|
+
* Maximum number of session-local events to keep in memory. `debug` events
|
|
21
|
+
* are evicted first; higher levels keep at most half of the buffer.
|
|
22
|
+
*/
|
|
20
23
|
maxEvents: number;
|
|
24
|
+
/**
|
|
25
|
+
* Minimum level forwarded to persistence sinks. Lower-level events stay in the
|
|
26
|
+
* live retained buffer only, so high-volume `debug` telemetry does not grow
|
|
27
|
+
* session files.
|
|
28
|
+
*/
|
|
29
|
+
persistLevel: DebugLevel;
|
|
21
30
|
}
|
|
22
31
|
|
|
23
32
|
export const DEBUG_REGISTRY_DEFAULTS: DebugRegistryConfig = {
|
|
@@ -25,8 +34,11 @@ export const DEBUG_REGISTRY_DEFAULTS: DebugRegistryConfig = {
|
|
|
25
34
|
agentAccess: "sanitized",
|
|
26
35
|
agentRunRetrospectivesEnabled: false,
|
|
27
36
|
maxEvents: 100,
|
|
37
|
+
persistLevel: "info",
|
|
28
38
|
};
|
|
29
39
|
|
|
40
|
+
const DEBUG_LEVEL_RANK: Record<DebugLevel, number> = { debug: 0, info: 1, warning: 2, error: 3 };
|
|
41
|
+
|
|
30
42
|
export interface DebugEventInput {
|
|
31
43
|
/** Opaque identity for events directly owned by one public Tool call. */
|
|
32
44
|
operationId?: string;
|
|
@@ -137,12 +149,51 @@ function normalizeMaxEvents(value: number): number {
|
|
|
137
149
|
return Math.floor(value);
|
|
138
150
|
}
|
|
139
151
|
|
|
152
|
+
function isSummary(event: DebugEvent): boolean {
|
|
153
|
+
return event.level !== "debug";
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
function groupKey(event: DebugEvent): string {
|
|
157
|
+
return `${event.source}\u0000${event.category}`;
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/**
|
|
161
|
+
* Return the index of the oldest event in the largest source/category group of
|
|
162
|
+
* one tier, so a high-volume category evicts its own events before rare ones.
|
|
163
|
+
*/
|
|
164
|
+
function evictionIndex(events: readonly DebugEvent[], summaryTier: boolean): number {
|
|
165
|
+
const counts = new Map<string, number>();
|
|
166
|
+
let largest = 0;
|
|
167
|
+
for (const event of events) {
|
|
168
|
+
if (isSummary(event) !== summaryTier) continue;
|
|
169
|
+
const key = groupKey(event);
|
|
170
|
+
const count = (counts.get(key) ?? 0) + 1;
|
|
171
|
+
counts.set(key, count);
|
|
172
|
+
largest = Math.max(largest, count);
|
|
173
|
+
}
|
|
174
|
+
return events.findIndex(
|
|
175
|
+
(event) => isSummary(event) === summaryTier && counts.get(groupKey(event)) === largest,
|
|
176
|
+
);
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* Evict down to `maxEvents`. A `debug` event goes first, so high-volume
|
|
181
|
+
* timings cannot push out a summary recorded moments earlier. Higher-level
|
|
182
|
+
* events keep at most half the buffer; past that one of them goes instead, so
|
|
183
|
+
* recent `debug` events stay visible too. Within the chosen tier, the oldest
|
|
184
|
+
* event of the largest source/category group goes, so one flooding category
|
|
185
|
+
* such as `request.timing` cannot push out every other category.
|
|
186
|
+
*/
|
|
140
187
|
function trimToMaxEvents(state: DebugRegistryState): void {
|
|
141
188
|
const maxEvents = normalizeMaxEvents(state.config.maxEvents);
|
|
142
|
-
|
|
143
|
-
|
|
189
|
+
const summaryShare = Math.floor(maxEvents / 2);
|
|
190
|
+
let summaries = state.events.filter(isSummary).length;
|
|
191
|
+
while (state.events.length > maxEvents) {
|
|
192
|
+
const evictSummary = summaries > summaryShare;
|
|
193
|
+
const index = evictionIndex(state.events, evictSummary);
|
|
194
|
+
if (evictSummary) summaries--;
|
|
195
|
+
state.events.splice(Math.max(index, 0), 1);
|
|
144
196
|
}
|
|
145
|
-
state.events.splice(0, state.events.length - maxEvents);
|
|
146
197
|
}
|
|
147
198
|
|
|
148
199
|
/** Return whether a debug level is recognized by the registry. */
|
|
@@ -150,6 +201,10 @@ export function isDebugLevel(value: unknown): value is DebugLevel {
|
|
|
150
201
|
return value === "debug" || value === "info" || value === "warning" || value === "error";
|
|
151
202
|
}
|
|
152
203
|
|
|
204
|
+
function shouldPersist(state: DebugRegistryState, level: DebugLevel): boolean {
|
|
205
|
+
return DEBUG_LEVEL_RANK[level] >= DEBUG_LEVEL_RANK[state.config.persistLevel];
|
|
206
|
+
}
|
|
207
|
+
|
|
153
208
|
/** Return whether a value has the exact 16-byte base64url Debug Operation ID form. */
|
|
154
209
|
export function isDebugOperationId(value: unknown): value is string {
|
|
155
210
|
return typeof value === "string" && DEBUG_OPERATION_ID_RE.test(value);
|
|
@@ -194,6 +249,9 @@ export function configureDebugRegistry(config: Partial<DebugRegistryConfig>): De
|
|
|
194
249
|
...state.config,
|
|
195
250
|
...config,
|
|
196
251
|
maxEvents: normalizeMaxEvents(config.maxEvents ?? state.config.maxEvents),
|
|
252
|
+
persistLevel: isDebugLevel(config.persistLevel)
|
|
253
|
+
? config.persistLevel
|
|
254
|
+
: state.config.persistLevel,
|
|
197
255
|
};
|
|
198
256
|
trimToMaxEvents(state);
|
|
199
257
|
return getDebugRegistryConfig();
|
|
@@ -210,16 +268,22 @@ export function isDebugRegistryEnabled(): boolean {
|
|
|
210
268
|
}
|
|
211
269
|
|
|
212
270
|
/**
|
|
213
|
-
* Return whether
|
|
214
|
-
* must be enabled,
|
|
271
|
+
* Return whether an event at `level` would reach the session file now: Debug
|
|
272
|
+
* must be enabled, at least one persistence sink must be registered, and the
|
|
273
|
+
* persistence threshold must admit the level.
|
|
215
274
|
*/
|
|
216
|
-
export function
|
|
275
|
+
export function canPersistDebugEvent(level: DebugLevel = "info"): boolean {
|
|
217
276
|
const state = getState();
|
|
218
|
-
return (
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
277
|
+
return state.config.enabled && state.persistenceSinks.size > 0 && shouldPersist(state, level);
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
/**
|
|
281
|
+
* Return whether a retrospective can be captured: an `info` event must be
|
|
282
|
+
* persistable (see {@link canPersistDebugEvent}) and the explicit Agent Run
|
|
283
|
+
* retrospective opt-in must be enabled.
|
|
284
|
+
*/
|
|
285
|
+
export function canRecordAgentRunRetrospective(): boolean {
|
|
286
|
+
return getState().config.agentRunRetrospectivesEnabled && canPersistDebugEvent("info");
|
|
223
287
|
}
|
|
224
288
|
|
|
225
289
|
/** Best-effort redaction helper for data exposed through sanitized debug views. */
|
|
@@ -283,7 +347,8 @@ export function recordDebugEvent(input: DebugEventInput): DebugEvent | null {
|
|
|
283
347
|
// Debug-event consumers must not alter producer behavior.
|
|
284
348
|
}
|
|
285
349
|
}
|
|
286
|
-
|
|
350
|
+
const sinks = shouldPersist(state, event.level) ? state.persistenceSinks : [];
|
|
351
|
+
for (const sink of sinks) {
|
|
287
352
|
try {
|
|
288
353
|
sink(toSanitizedView(event));
|
|
289
354
|
} catch {
|
|
@@ -1,9 +1,8 @@
|
|
|
1
1
|
// Shared footer contribution registry for SuPi extensions.
|
|
2
2
|
//
|
|
3
|
-
// Extensions register
|
|
4
|
-
//
|
|
5
|
-
//
|
|
6
|
-
// alongside the built-in metrics. Extensions can use PI's status API as a
|
|
3
|
+
// Extensions register text chunks with a placement hint. The custom footer in
|
|
4
|
+
// supi-extras reads these contributions and renders them alongside the
|
|
5
|
+
// built-in metrics. Extensions can use PI's status API with the same key as a
|
|
7
6
|
// fallback when the custom footer is not installed.
|
|
8
7
|
|
|
9
8
|
import { createRegistry } from "./registry-utils.ts";
|
|
@@ -11,8 +10,33 @@ import { createRegistry } from "./registry-utils.ts";
|
|
|
11
10
|
/** Event emitted when a dynamic footer contribution needs a new render. */
|
|
12
11
|
export const FOOTER_INVALIDATE_EVENT = "supi:footer:invalidate";
|
|
13
12
|
|
|
14
|
-
/**
|
|
15
|
-
|
|
13
|
+
/**
|
|
14
|
+
* Where the contribution should appear in the footer.
|
|
15
|
+
*
|
|
16
|
+
* - `path-end`: right side of the workspace line (path and Git), for workspace state
|
|
17
|
+
* - `stats`: inside the cache section of the session line
|
|
18
|
+
* - `stats-end`: own sections after context usage on the session line
|
|
19
|
+
* - `model-start`: right side of the session line, before the model name
|
|
20
|
+
* - `status`: extension status line below the footer
|
|
21
|
+
*/
|
|
22
|
+
export type FooterPlacement = "path-end" | "stats" | "stats-end" | "model-start" | "status";
|
|
23
|
+
|
|
24
|
+
/** Icon set selected by the footer `icons` setting. */
|
|
25
|
+
export type FooterGlyphMode = "nerd" | "unicode" | "ascii";
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Theme color names accepted by {@link FooterRenderContext.style}.
|
|
29
|
+
* Matches the Pi `ThemeColor` names SuPi contributions use.
|
|
30
|
+
*/
|
|
31
|
+
export type FooterColor = "accent" | "dim" | "muted" | "text" | "success" | "warning" | "error";
|
|
32
|
+
|
|
33
|
+
/** Render inputs supplied by the custom footer. */
|
|
34
|
+
export interface FooterRenderContext {
|
|
35
|
+
/** Apply a theme color. */
|
|
36
|
+
style: (color: FooterColor, text: string) => string;
|
|
37
|
+
/** Resolved icon mode; contributions choose matching glyphs. */
|
|
38
|
+
glyphMode: FooterGlyphMode;
|
|
39
|
+
}
|
|
16
40
|
|
|
17
41
|
/** A single footer contribution registered by an extension. */
|
|
18
42
|
export interface FooterContribution {
|
|
@@ -21,15 +45,18 @@ export interface FooterContribution {
|
|
|
21
45
|
* A same-key Pi status is treated as this contribution's built-in-footer fallback.
|
|
22
46
|
*/
|
|
23
47
|
key: string;
|
|
24
|
-
/** Which footer
|
|
48
|
+
/** Which footer area this belongs to. */
|
|
25
49
|
placement: FooterPlacement;
|
|
26
50
|
/**
|
|
27
51
|
* Sort order within the placement (lower values render further left). Default: 100.
|
|
28
52
|
* Priority 0 is reserved for the turn cache-hit part so it stays adjacent to CH.
|
|
29
53
|
*/
|
|
30
54
|
priority?: number;
|
|
31
|
-
/**
|
|
32
|
-
|
|
55
|
+
/**
|
|
56
|
+
* Return the text for this contribution; empty hides it. Called on every render.
|
|
57
|
+
* Callers without a footer context (for example tests) may omit `ctx`.
|
|
58
|
+
*/
|
|
59
|
+
render: (ctx?: FooterRenderContext) => string;
|
|
33
60
|
}
|
|
34
61
|
|
|
35
62
|
const registry = createRegistry<FooterContribution>("footer-contributions");
|
|
@@ -57,6 +84,11 @@ export const footerContributions = {
|
|
|
57
84
|
.sort(sortByPriority);
|
|
58
85
|
},
|
|
59
86
|
|
|
87
|
+
/** Get every registered contribution regardless of placement. */
|
|
88
|
+
getAll(): FooterContribution[] {
|
|
89
|
+
return registry.getAll();
|
|
90
|
+
},
|
|
91
|
+
|
|
60
92
|
/** Remove all contributions (primarily for tests). */
|
|
61
93
|
clear(): void {
|
|
62
94
|
registry.clear();
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
// supi-core retired-packages domain — warn when a retired SuPi package is still declared.
|
|
2
|
+
//
|
|
3
|
+
// Retired packages keep loading after an upgrade until the user removes them, and their
|
|
4
|
+
// surfaces can shadow the package that absorbed them. Detection reads the declared Pi
|
|
5
|
+
// packages per scope, the same view `pi remove` acts on, and never infers identity from paths.
|
|
6
|
+
|
|
7
|
+
import type {
|
|
8
|
+
ExtensionAPI,
|
|
9
|
+
ExtensionContext,
|
|
10
|
+
PackageSource,
|
|
11
|
+
} from "@earendil-works/pi-coding-agent";
|
|
12
|
+
import { SettingsManager } from "@earendil-works/pi-coding-agent";
|
|
13
|
+
import { recordDebugEvent } from "./debug-registry.ts";
|
|
14
|
+
|
|
15
|
+
/** A retired npm package and the package that now ships its features. */
|
|
16
|
+
export interface RetiredPackage {
|
|
17
|
+
/** npm package name, e.g. `"@mrclrchtr/supi-cache"`. */
|
|
18
|
+
name: string;
|
|
19
|
+
/** npm package name that absorbed it, e.g. `"@mrclrchtr/supi-debug"`. */
|
|
20
|
+
replacement: string;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/** Pi settings scope of a package declaration. */
|
|
24
|
+
export type PackageDeclarationScope = "user" | "project";
|
|
25
|
+
|
|
26
|
+
/** One declaration of a retired package found in Pi settings. */
|
|
27
|
+
export interface RetiredPackageDeclaration {
|
|
28
|
+
package: RetiredPackage;
|
|
29
|
+
scope: PackageDeclarationScope;
|
|
30
|
+
/** Exact command that removes this declaration. */
|
|
31
|
+
removeCommand: string;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** Declared Pi packages per scope. Omit `project` when the project is not trusted. */
|
|
35
|
+
export interface DeclaredPackages {
|
|
36
|
+
user: readonly PackageSource[];
|
|
37
|
+
project?: readonly PackageSource[];
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** Options for {@link warnRetiredPackages}. */
|
|
41
|
+
export interface WarnRetiredPackagesOptions {
|
|
42
|
+
/** Debug event source, e.g. `"supi-debug"`. */
|
|
43
|
+
source: string;
|
|
44
|
+
/** Override Pi's agent directory (tests). */
|
|
45
|
+
agentDir?: string;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
const WARNED_KEY = Symbol.for("@mrclrchtr/supi-core/retired-packages-warned");
|
|
49
|
+
const NPM_PREFIX = "npm:";
|
|
50
|
+
const NPM_NAME_RE = /^(@[^/\s]+\/[^@\s]+|[^@\s]+)(?:@.+)?$/;
|
|
51
|
+
|
|
52
|
+
/** npm package name of a Pi package source, ignoring version pins; `undefined` for non-npm sources. */
|
|
53
|
+
export function npmPackageName(source: PackageSource): string | undefined {
|
|
54
|
+
const value = (typeof source === "string" ? source : source.source).trim();
|
|
55
|
+
if (!value.startsWith(NPM_PREFIX)) return undefined;
|
|
56
|
+
return NPM_NAME_RE.exec(value.slice(NPM_PREFIX.length).trim())?.[1];
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** Find declarations of retired packages, project scope first (Pi's load precedence). */
|
|
60
|
+
export function findRetiredPackageDeclarations(
|
|
61
|
+
declared: DeclaredPackages,
|
|
62
|
+
retired: readonly RetiredPackage[],
|
|
63
|
+
): RetiredPackageDeclaration[] {
|
|
64
|
+
const scopes: Array<[PackageDeclarationScope, readonly PackageSource[] | undefined]> = [
|
|
65
|
+
["project", declared.project],
|
|
66
|
+
["user", declared.user],
|
|
67
|
+
];
|
|
68
|
+
const found: RetiredPackageDeclaration[] = [];
|
|
69
|
+
for (const [scope, sources] of scopes) {
|
|
70
|
+
const names = new Set((sources ?? []).map(npmPackageName));
|
|
71
|
+
for (const pkg of retired) {
|
|
72
|
+
if (!names.has(pkg.name)) continue;
|
|
73
|
+
const local = scope === "project" ? " --local" : "";
|
|
74
|
+
found.push({ package: pkg, scope, removeCommand: `pi remove npm:${pkg.name}${local}` });
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
return found;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** Format one bounded, actionable warning for one retired package. */
|
|
81
|
+
export function formatRetiredPackageWarning(
|
|
82
|
+
pkg: RetiredPackage,
|
|
83
|
+
declarations: readonly RetiredPackageDeclaration[],
|
|
84
|
+
): string {
|
|
85
|
+
const commands = declarations.map((declaration) => ` ${declaration.removeCommand}`);
|
|
86
|
+
return [
|
|
87
|
+
`${pkg.name} is retired; ${pkg.replacement} now ships its features, and the old package can override them. Remove it:`,
|
|
88
|
+
...commands,
|
|
89
|
+
].join("\n");
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
function warnedNames(): Set<string> {
|
|
93
|
+
const store = globalThis as Record<symbol, Set<string> | undefined>;
|
|
94
|
+
store[WARNED_KEY] ??= new Set();
|
|
95
|
+
return store[WARNED_KEY];
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
function readDeclaredPackages(
|
|
99
|
+
ctx: Pick<ExtensionContext, "cwd" | "isProjectTrusted">,
|
|
100
|
+
agentDir: string | undefined,
|
|
101
|
+
): DeclaredPackages {
|
|
102
|
+
const projectTrusted = ctx.isProjectTrusted();
|
|
103
|
+
const settings = SettingsManager.create(ctx.cwd, agentDir, { projectTrusted });
|
|
104
|
+
return {
|
|
105
|
+
user: settings.getGlobalSettings().packages ?? [],
|
|
106
|
+
...(projectTrusted ? { project: settings.getProjectSettings().packages ?? [] } : {}),
|
|
107
|
+
};
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* Warn once per Pi process for each retired package that is still declared in user or
|
|
112
|
+
* trusted project settings. Shows a UI warning, or writes to stderr without UI, and records
|
|
113
|
+
* a `retired-package` Debug event. Never throws; unreadable settings skip the check.
|
|
114
|
+
*/
|
|
115
|
+
export function warnRetiredPackages(
|
|
116
|
+
pi: ExtensionAPI,
|
|
117
|
+
retired: readonly RetiredPackage[],
|
|
118
|
+
options: WarnRetiredPackagesOptions,
|
|
119
|
+
): void {
|
|
120
|
+
pi.on("session_start", (_event, ctx) => {
|
|
121
|
+
const warned = warnedNames();
|
|
122
|
+
const pending = retired.filter((pkg) => !warned.has(pkg.name));
|
|
123
|
+
if (pending.length === 0) return;
|
|
124
|
+
|
|
125
|
+
let declarations: RetiredPackageDeclaration[];
|
|
126
|
+
try {
|
|
127
|
+
declarations = findRetiredPackageDeclarations(
|
|
128
|
+
readDeclaredPackages(ctx, options.agentDir),
|
|
129
|
+
pending,
|
|
130
|
+
);
|
|
131
|
+
} catch {
|
|
132
|
+
return;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
for (const pkg of pending) {
|
|
136
|
+
const matches = declarations.filter((declaration) => declaration.package === pkg);
|
|
137
|
+
if (matches.length === 0) continue;
|
|
138
|
+
warned.add(pkg.name);
|
|
139
|
+
const message = formatRetiredPackageWarning(pkg, matches);
|
|
140
|
+
if (ctx.hasUI) ctx.ui.notify(message, "warning");
|
|
141
|
+
else process.stderr.write(`${message}\n`);
|
|
142
|
+
recordDebugEvent({
|
|
143
|
+
source: options.source,
|
|
144
|
+
level: "warning",
|
|
145
|
+
category: "retired-package",
|
|
146
|
+
message: `${pkg.name} is retired but still declared`,
|
|
147
|
+
cwd: ctx.cwd,
|
|
148
|
+
data: { name: pkg.name, replacement: pkg.replacement, scopes: matches.map((m) => m.scope) },
|
|
149
|
+
});
|
|
150
|
+
}
|
|
151
|
+
});
|
|
152
|
+
}
|
|
@@ -56,3 +56,6 @@ export {
|
|
|
56
56
|
createSessionNameTracker,
|
|
57
57
|
getActiveBranchEntries,
|
|
58
58
|
} from "./session-utils.ts";
|
|
59
|
+
export { BSD_SED_HINT, BSD_SED_HINT_MARKER, registerShellHints } from "./shell-hints.ts";
|
|
60
|
+
export type { SideRunEvent } from "./side-run.ts";
|
|
61
|
+
export { runSideRun, SIDE_RUN_END_EVENT, SIDE_RUN_START_EVENT } from "./side-run.ts";
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
// Shell hints — explain BSD sed script errors once per session.
|
|
2
|
+
//
|
|
3
|
+
// On macOS, `sed` is BSD sed: `-i` requires a backup-suffix argument and script errors read
|
|
4
|
+
// `sed: 1: "...": ...`. Agents trained on GNU sed retry the same shape repeatedly. This hook adds
|
|
5
|
+
// one hint to the first matching bash result in a session. It costs no context until it fires.
|
|
6
|
+
|
|
7
|
+
import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
8
|
+
|
|
9
|
+
/** Marker that identifies the hint in tool results and on the session branch. */
|
|
10
|
+
export const BSD_SED_HINT_MARKER = "[supi shell hint]";
|
|
11
|
+
|
|
12
|
+
/** Text appended to the first BSD sed script error in a session. */
|
|
13
|
+
export const BSD_SED_HINT = `${BSD_SED_HINT_MARKER} This is BSD sed (macOS): \`sed -i\` needs a suffix argument (\`sed -i '' ...\`), and the substitute delimiter must not occur in the pattern. Prefer the edit tool for file changes when it is available, or \`gsed\` if installed.`;
|
|
14
|
+
|
|
15
|
+
const BSD_SED_ERROR = /^sed: (?:\d+: |-i may not be used|-I or -i may not be used)/m;
|
|
16
|
+
|
|
17
|
+
function resultText(content: readonly { type: string; text?: string }[]): string {
|
|
18
|
+
return content.map((part) => (part.type === "text" ? (part.text ?? "") : "")).join("\n");
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
function hintAlreadyShown(ctx: ExtensionContext): boolean {
|
|
22
|
+
return ctx.sessionManager
|
|
23
|
+
.getBranch()
|
|
24
|
+
.some(
|
|
25
|
+
(entry) =>
|
|
26
|
+
entry.type === "message" &&
|
|
27
|
+
entry.message.role === "toolResult" &&
|
|
28
|
+
JSON.stringify(entry.message.content).includes(BSD_SED_HINT_MARKER),
|
|
29
|
+
);
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Register a `tool_result` hook that appends {@link BSD_SED_HINT} to the first bash result in a
|
|
34
|
+
* session that contains a BSD sed script error. Safe to register from several extensions: the hook
|
|
35
|
+
* skips results that already carry the hint and sessions whose branch already shows it.
|
|
36
|
+
* Usable directly as a child-session extension factory.
|
|
37
|
+
*/
|
|
38
|
+
export function registerShellHints(pi: ExtensionAPI): void {
|
|
39
|
+
pi.on("tool_result", (event, ctx) => {
|
|
40
|
+
if (event.toolName !== "bash") return;
|
|
41
|
+
const text = resultText(event.content);
|
|
42
|
+
if (!BSD_SED_ERROR.test(text) || text.includes(BSD_SED_HINT_MARKER)) return;
|
|
43
|
+
if (hintAlreadyShown(ctx)) return;
|
|
44
|
+
return { content: [...event.content, { type: "text", text: BSD_SED_HINT }] };
|
|
45
|
+
});
|
|
46
|
+
}
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
// Side-run signal shared over `pi.events`.
|
|
2
|
+
//
|
|
3
|
+
// A side run is agent work whose result the session will not continue from,
|
|
4
|
+
// such as a run on a branch that is abandoned afterwards. Listeners use the
|
|
5
|
+
// signal to skip work tied to the run's result, for example prompt suggestions.
|
|
6
|
+
|
|
7
|
+
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
8
|
+
|
|
9
|
+
/** Event emitted on `pi.events` when a side run starts. Payload: {@link SideRunEvent}. */
|
|
10
|
+
export const SIDE_RUN_START_EVENT = "supi:side-run:start";
|
|
11
|
+
|
|
12
|
+
/** Event emitted on `pi.events` when a side run ends. Payload: {@link SideRunEvent}. */
|
|
13
|
+
export const SIDE_RUN_END_EVENT = "supi:side-run:end";
|
|
14
|
+
|
|
15
|
+
/** Payload of {@link SIDE_RUN_START_EVENT} and {@link SIDE_RUN_END_EVENT}. */
|
|
16
|
+
export interface SideRunEvent {
|
|
17
|
+
/** Emitting package, such as `supi-debug`. */
|
|
18
|
+
readonly source: string;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Run `run` as a side run: emit {@link SIDE_RUN_START_EVENT} before it and
|
|
23
|
+
* {@link SIDE_RUN_END_EVENT} after it, also when it throws.
|
|
24
|
+
*
|
|
25
|
+
* After a session replacement or reload the captured `pi` is stale and its
|
|
26
|
+
* `events.emit` throws. That end signal is dropped instead of masking the
|
|
27
|
+
* run's result; listeners reset their side-run state on `session_start` and
|
|
28
|
+
* `session_shutdown`.
|
|
29
|
+
*/
|
|
30
|
+
export async function runSideRun<T>(
|
|
31
|
+
pi: Pick<ExtensionAPI, "events">,
|
|
32
|
+
source: string,
|
|
33
|
+
run: () => Promise<T>,
|
|
34
|
+
): Promise<T> {
|
|
35
|
+
const payload: SideRunEvent = { source };
|
|
36
|
+
pi.events.emit(SIDE_RUN_START_EVENT, payload);
|
|
37
|
+
try {
|
|
38
|
+
return await run();
|
|
39
|
+
} finally {
|
|
40
|
+
try {
|
|
41
|
+
pi.events.emit(SIDE_RUN_END_EVENT, payload);
|
|
42
|
+
} catch {
|
|
43
|
+
// Stale extension instance after session replacement; see JSDoc.
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
}
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
// supi-core spill domain — create-only temp files for full tool output (#597).
|
|
2
|
+
//
|
|
3
|
+
// SuPi never deletes spill files. Instead, it writes few of them: one private base directory per
|
|
4
|
+
// user, content-addressed names, and reuse for identical content. The OS temp purge owns their
|
|
5
|
+
// lifetime, so paths returned to the model stay readable for the session.
|
|
6
|
+
|
|
7
|
+
import { createHash, randomBytes } from "node:crypto";
|
|
8
|
+
import { lstatSync, mkdirSync, mkdtempSync, renameSync, writeFileSync } from "node:fs";
|
|
9
|
+
import { tmpdir } from "node:os";
|
|
10
|
+
import { extname, join } from "node:path";
|
|
11
|
+
|
|
12
|
+
/** Input for {@link writeSpillFile}. */
|
|
13
|
+
export interface SpillFileOptions {
|
|
14
|
+
/** Producer id used as sub-directory, e.g. `"agent"`. Lowercase letters, digits, and dashes. */
|
|
15
|
+
owner: string;
|
|
16
|
+
/** Descriptive file name, e.g. `"snapshot.md"`. The content hash is inserted before the extension. */
|
|
17
|
+
name: string;
|
|
18
|
+
/** Full content to persist: text (written as UTF-8) or raw bytes. */
|
|
19
|
+
content: string | Uint8Array;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
const SEGMENT = /^[a-z0-9][a-z0-9-]*$/;
|
|
23
|
+
const FILE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* Persist full output that did not fit inline and return its absolute path.
|
|
27
|
+
*
|
|
28
|
+
* Layout: `$TMPDIR/supi-<uid>/<owner>/<stem>-<sha256 prefix><ext>`. Identical content maps to the
|
|
29
|
+
* same file, which is reused. Both directories must be real directories owned by the current
|
|
30
|
+
* user without group/other access; otherwise the file falls back to a fresh `mkdtemp`
|
|
31
|
+
* directory, as before. Files are created with mode `0600` and published atomically by rename.
|
|
32
|
+
*/
|
|
33
|
+
export function writeSpillFile({ owner, name, content }: SpillFileOptions): string {
|
|
34
|
+
if (!SEGMENT.test(owner)) throw new Error(`Invalid spill owner: ${owner}`);
|
|
35
|
+
if (!FILE_NAME.test(name)) throw new Error(`Invalid spill file name: ${name}`);
|
|
36
|
+
const extension = extname(name);
|
|
37
|
+
const stem = name.slice(0, name.length - extension.length);
|
|
38
|
+
const hash = createHash("sha256").update(content).digest("hex").slice(0, 32);
|
|
39
|
+
const fileName = `${stem}-${hash}${extension}`;
|
|
40
|
+
|
|
41
|
+
const directory = privateSpillDirectory(owner);
|
|
42
|
+
if (!directory) {
|
|
43
|
+
const fallback = join(mkdtempSync(join(tmpdir(), `supi-${owner}-`)), fileName);
|
|
44
|
+
writeFileSync(fallback, content, { encoding: "utf8", mode: 0o600, flag: "wx" });
|
|
45
|
+
return fallback;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
const target = join(directory, fileName);
|
|
49
|
+
if (isRegularFile(target)) return target;
|
|
50
|
+
const staging = join(directory, `.${fileName}.${process.pid}.${randomBytes(4).toString("hex")}`);
|
|
51
|
+
writeFileSync(staging, content, { encoding: "utf8", mode: 0o600, flag: "wx" });
|
|
52
|
+
// Atomic publish; a concurrent writer of the same hash replaces it with identical bytes.
|
|
53
|
+
renameSync(staging, target);
|
|
54
|
+
return target;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** Return the validated private spill directory for `owner`, or undefined when it is unsafe. */
|
|
58
|
+
function privateSpillDirectory(owner: string): string | undefined {
|
|
59
|
+
const uid = process.getuid?.();
|
|
60
|
+
const base = join(tmpdir(), uid === undefined ? "supi" : `supi-${uid}`);
|
|
61
|
+
if (!ensurePrivateDirectory(base, uid)) return undefined;
|
|
62
|
+
const directory = join(base, owner);
|
|
63
|
+
return ensurePrivateDirectory(directory, uid) ? directory : undefined;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Create `path` with mode `0700` if missing, then accept it only when it is a real directory
|
|
68
|
+
* (not a symlink) owned by `uid` with no group/other permissions. Never modifies or removes an
|
|
69
|
+
* existing entry. Ownership and mode checks are skipped where POSIX ids are unavailable.
|
|
70
|
+
*/
|
|
71
|
+
function ensurePrivateDirectory(path: string, uid: number | undefined): boolean {
|
|
72
|
+
try {
|
|
73
|
+
mkdirSync(path, { mode: 0o700 });
|
|
74
|
+
} catch (error) {
|
|
75
|
+
if ((error as NodeJS.ErrnoException).code !== "EEXIST") return false;
|
|
76
|
+
}
|
|
77
|
+
try {
|
|
78
|
+
const stats = lstatSync(path);
|
|
79
|
+
if (!stats.isDirectory() || stats.isSymbolicLink()) return false;
|
|
80
|
+
if (uid === undefined) return true;
|
|
81
|
+
return stats.uid === uid && (stats.mode & 0o077) === 0;
|
|
82
|
+
} catch {
|
|
83
|
+
return false;
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
function isRegularFile(path: string): boolean {
|
|
88
|
+
try {
|
|
89
|
+
return lstatSync(path).isFile();
|
|
90
|
+
} catch {
|
|
91
|
+
return false;
|
|
92
|
+
}
|
|
93
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mrclrchtr/supi-context",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "14.0.0",
|
|
4
4
|
"description": "Live context pressure and token-use reports",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -32,7 +32,7 @@
|
|
|
32
32
|
"README.md"
|
|
33
33
|
],
|
|
34
34
|
"dependencies": {
|
|
35
|
-
"@mrclrchtr/supi-core": "
|
|
35
|
+
"@mrclrchtr/supi-core": "14.0.0"
|
|
36
36
|
},
|
|
37
37
|
"bundledDependencies": [
|
|
38
38
|
"@mrclrchtr/supi-core"
|
|
@@ -1,12 +1,10 @@
|
|
|
1
|
-
import { mkdtemp, writeFile } from "node:fs/promises";
|
|
2
|
-
import { tmpdir } from "node:os";
|
|
3
|
-
import { join } from "node:path";
|
|
4
1
|
import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
|
|
5
2
|
import {
|
|
6
3
|
DEFAULT_MAX_BYTES,
|
|
7
4
|
DEFAULT_MAX_LINES,
|
|
8
5
|
truncateHead,
|
|
9
6
|
} from "@earendil-works/pi-coding-agent";
|
|
7
|
+
import { writeSpillFile } from "@mrclrchtr/supi-core/spill";
|
|
10
8
|
import type { ContextAnalysis } from "../../analysis.ts";
|
|
11
9
|
import { type ContextPressureSnapshot, createContextPressureSnapshot } from "../../capacity.ts";
|
|
12
10
|
import type {
|
|
@@ -67,9 +65,11 @@ export async function buildFullResult(
|
|
|
67
65
|
let text = JSON.stringify(full);
|
|
68
66
|
const size = truncateHead(text, { maxLines: DEFAULT_MAX_LINES, maxBytes: DEFAULT_MAX_BYTES });
|
|
69
67
|
if (size.truncated) {
|
|
70
|
-
const
|
|
71
|
-
|
|
72
|
-
|
|
68
|
+
const path = writeSpillFile({
|
|
69
|
+
owner: "context",
|
|
70
|
+
name: "context-usage-report.json",
|
|
71
|
+
content: text,
|
|
72
|
+
});
|
|
73
73
|
data = { ...snapshot, attributionFile: { path, bytes: Buffer.byteLength(text, "utf8") } };
|
|
74
74
|
text = JSON.stringify(data);
|
|
75
75
|
}
|