@mrclrchtr/supi-ask-user 13.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.
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-core",
3
- "version": "13.0.0",
3
+ "version": "14.0.0",
4
4
  "description": "Shared settings, configuration, reporting, and session infrastructure",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -16,7 +16,10 @@ export interface DebugRegistryConfig {
16
16
  agentAccess: DebugAgentAccess;
17
17
  /** Whether Agent Run retrospective capture is explicitly enabled. */
18
18
  agentRunRetrospectivesEnabled: boolean;
19
- /** Maximum number of session-local events to keep in memory. */
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;
21
24
  /**
22
25
  * Minimum level forwarded to persistence sinks. Lower-level events stay in the
@@ -146,12 +149,51 @@ function normalizeMaxEvents(value: number): number {
146
149
  return Math.floor(value);
147
150
  }
148
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
+ */
149
187
  function trimToMaxEvents(state: DebugRegistryState): void {
150
188
  const maxEvents = normalizeMaxEvents(state.config.maxEvents);
151
- if (state.events.length <= maxEvents) {
152
- return;
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);
153
196
  }
154
- state.events.splice(0, state.events.length - maxEvents);
155
197
  }
156
198
 
157
199
  /** Return whether a debug level is recognized by the registry. */
@@ -226,18 +268,22 @@ export function isDebugRegistryEnabled(): boolean {
226
268
  }
227
269
 
228
270
  /**
229
- * Return whether a retrospective can be captured: Debug and its explicit opt-in
271
+ * Return whether an event at `level` would reach the session file now: Debug
230
272
  * must be enabled, at least one persistence sink must be registered, and the
231
- * persistence threshold must admit `info` events.
273
+ * persistence threshold must admit the level.
232
274
  */
233
- export function canRecordAgentRunRetrospective(): boolean {
275
+ export function canPersistDebugEvent(level: DebugLevel = "info"): boolean {
234
276
  const state = getState();
235
- return (
236
- state.config.enabled &&
237
- state.config.agentRunRetrospectivesEnabled &&
238
- state.persistenceSinks.size > 0 &&
239
- shouldPersist(state, "info")
240
- );
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");
241
287
  }
242
288
 
243
289
  /** Best-effort redaction helper for data exposed through sanitized debug views. */
@@ -1,9 +1,8 @@
1
1
  // Shared footer contribution registry for SuPi extensions.
2
2
  //
3
- // Extensions register pre-styled text chunks with a placement hint
4
- // ("stats" for the metrics line, "status" for the extension status line).
5
- // The custom footer in supi-extras reads these contributions and renders them
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
- /** Where the contribution should appear in the footer. */
15
- export type FooterPlacement = "stats" | "stats-end" | "status";
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 line this belongs on. */
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
- /** Return the pre-styled text for this contribution. Called on every render. */
32
- render: () => string;
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();
@@ -57,3 +57,5 @@ export {
57
57
  getActiveBranchEntries,
58
58
  } from "./session-utils.ts";
59
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
+ // 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
+ }
@@ -15,8 +15,8 @@ export interface SpillFileOptions {
15
15
  owner: string;
16
16
  /** Descriptive file name, e.g. `"snapshot.md"`. The content hash is inserted before the extension. */
17
17
  name: string;
18
- /** Full content to persist. */
19
- content: string;
18
+ /** Full content to persist: text (written as UTF-8) or raw bytes. */
19
+ content: string | Uint8Array;
20
20
  }
21
21
 
22
22
  const SEGMENT = /^[a-z0-9][a-z0-9-]*$/;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-ask-user",
3
- "version": "13.0.0",
3
+ "version": "14.0.0",
4
4
  "description": "Structured choice and text forms for agent-user decisions",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -33,7 +33,7 @@
33
33
  "!__tests__"
34
34
  ],
35
35
  "dependencies": {
36
- "@mrclrchtr/supi-core": "13.0.0"
36
+ "@mrclrchtr/supi-core": "14.0.0"
37
37
  },
38
38
  "bundledDependencies": [
39
39
  "@mrclrchtr/supi-core"