@mrclrchtr/supi-prompt-suggestions 4.7.0 → 4.9.0

package/README.md

@@ -34,11 +34,12 @@ Suggestions only appear when:
 
 | Key | Action |
 |-----|--------|
-| `→` / Right Arrow | Accept the suggestion into the editor without submitting it |
-| `Esc` | Dismiss the suggestion |
-| Any text input | Dismiss the suggestion and continue typing |
+| `→` / Right Arrow / `Tab` | Accept the suggestion into the editor without submitting it |
+| `Esc` | Dismiss the visible suggestion |
+| Any text input | Hide the suggestion and continue typing |
+| Delete all editor text | Restore the hidden suggestion |
 
-Accepted suggestions are inserted into the editor so you can edit them before sending.
+Accepted suggestions are inserted into the editor so you can edit them before sending. A hidden suggestion remains available until you accept it, dismiss it, or start new agent work.
 
 ## Configuration
 

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -37,33 +37,18 @@ Config file locations:
 
 ### Settings helpers
 
-- `registerDeclarativeSettings(pi, options)` — contribute a config-backed declarative settings section with source-aware scoped persistence
-- `registerSettingsCommand(pi)` — register `/supi-settings` (used by `@mrclrchtr/supi-settings`)
-- `openSettingsOverlay(pi, ctx)` — open the shared settings UI directly
-- `createInputSubmenu()` — helper for simple text-entry submenus
-- `createModelPickerSubmenu()` — helper for scoped model selection submenus, with optional host-owned choices and `disabled` control
-
-The built-in settings UI supports:
-
-- project/global scope toggle
-- source badges for project, global, and default values
-- Inherit/Reset actions that delete scoped config keys
-- grouped extension sections
-- searchable setting lists
+- `registerSettings(pi, module)` — register one canonical asynchronous settings module
+- `defineConfigSettings(options)` — adapt a fixed SuPi config section to that module interface
+- settings registry helpers and types for the `@mrclrchtr/supi-settings` configuration surface
 
 ### Context helpers
 
 - `wrapExtensionContext()` — wrap injected text in SuPi's `<extension-context>` tag
-- `findLastUserMessageIndex()`
-- `getContextToken()`
-- `getPromptContent()`
-- `pruneAndReorderContextMessages()`
-- `restorePromptContent()`
 
 ### Shared registries
 
 - context-provider registry for `/supi-context`
-- debug-event registry for producers that want shared debug capture
+- debug-event registry and monotonic phase timers for producers that want shared debug capture
 - settings registry used by `/supi-settings`
 
 ### Project and session helpers
@@ -84,25 +69,33 @@ The built-in settings UI supports:
 
 ```ts
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { loadSupiConfig, registerDeclarativeSettings, wrapExtensionContext } from "@mrclrchtr/supi-core/api";
+import {
+  defineConfigSettings,
+  loadSupiConfig,
+  registerSettings,
+  wrapExtensionContext,
+} from "@mrclrchtr/supi-core/api";
 
 export default function myExtension(pi: ExtensionAPI) {
   const defaults = { enabled: true };
   const config = loadSupiConfig("my-extension", process.cwd(), defaults);
 
-  registerDeclarativeSettings(pi, {
-    id: "my-extension",
-    label: "My Extension",
-    section: "my-extension",
-    defaults,
-    fields: [
-      {
-        kind: "boolean" as const,
-        key: "enabled",
-        label: "Enabled",
-      },
-    ],
-  });
+  registerSettings(
+    pi,
+    defineConfigSettings({
+      id: "my-extension",
+      label: "My Extension",
+      section: "my-extension",
+      defaults,
+      fields: [
+        {
+          kind: "boolean" as const,
+          key: "enabled",
+          label: "Enabled",
+        },
+      ],
+    }),
+  );
 
   const message = wrapExtensionContext("my-extension", "hello", {
     enabled: config.enabled,
@@ -115,6 +108,7 @@ export default function myExtension(pi: ExtensionAPI) {
 
 - `src/api.ts` — exported library surface
 - `src/config.ts` — shared config loading and writing
-- `src/config-settings.ts` — config-backed settings registration helper
-- `src/settings-ui.ts` — shared settings overlay
+- `src/debug-registry.ts` — Debug domain surface, event state, retention, redaction, listeners, and queries
+- `src/debug-timing.ts` — monotonic total and phase timers for Debug Event Producers
+- `src/settings/` — settings registry, schema, scope resolution, and persistence
 - `src/report.ts` — shared text/report rendering helpers

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "4.7.0",
+  "version": "4.9.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {
@@ -60,16 +60,13 @@
     "./model-selection": "./src/model-selection.ts",
     "./package.json": "./package.json",
     "./path": "./src/path.ts",
-    "./report": "./src/report.ts",
-    "./progress-widget": "./src/progress-widget.ts",
     "./project": "./src/project.ts",
+    "./prompt-surface": "./src/prompt-surface.ts",
+    "./report": "./src/report.ts",
     "./session": "./src/session.ts",
     "./settings": "./src/settings.ts",
-    "./settings-ui": "./src/settings-ui.ts",
     "./spinner-frames": "./src/spinner-frames.ts",
     "./status-spinner": "./src/status-spinner.ts",
-    "./terminal": "./src/terminal.ts",
-    "./tool-framework": "./src/tool-framework.ts",
-    "./prompt-surface": "./src/prompt-surface.ts"
+    "./terminal": "./src/terminal.ts"
   }
 }

package/node_modules/@mrclrchtr/supi-core/src/api.ts

@@ -1,6 +1,6 @@
 // supi-core — shared infrastructure for SuPi extensions.
-// Provides XML context tag wrapping, unified config system, context-message utilities,
-// settings registry for supi-wide TUI settings, and a shared tool-spec/registration framework.
+// Provides XML context tag wrapping, unified config, prompt-surface resolution,
+// and shared settings, reporting, and session utilities.
 //
 // Convenience barrel — re-exports all domain entry points.
 // For lighter imports, use one of the domain subpaths directly
@@ -25,18 +25,16 @@ export * from "./path.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./project.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./prompt-surface.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./report.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./session.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./settings.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./settings-ui.ts";
-// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./spinner-frames.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./status-spinner.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./terminal.ts";
-// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./tool-framework.ts";

package/node_modules/@mrclrchtr/supi-core/src/config/config.ts

@@ -199,23 +199,3 @@ function extractSection(
   }
   return null;
 }
-
-/**
- * Shorthand for {@link loadSupiConfig} that infers the return type from defaults.
- *
- * Reduces boilerplate when a package only needs the merged runtime config.
- *
- * @example
- * ```ts
- * const config = loadSectionConfig("my-ext", cwd, { enabled: true, timeout: 30 });
- * // config is typed as { enabled: boolean; timeout: number }
- * ```
- */
-export function loadSectionConfig<T extends Record<string, unknown>>(
-  section: string,
-  cwd: string,
-  defaults: T,
-  options?: SupiConfigOptions,
-): T {
-  return loadSupiConfig(section, cwd, defaults, options);
-}

package/node_modules/@mrclrchtr/supi-core/src/config/prompt-surface.ts

@@ -8,11 +8,17 @@ import {
   type ExtensionContext,
   hasTrustRequiringProjectResources,
 } from "@earendil-works/pi-coding-agent";
-import type { SuiPiToolPromptSurface } from "../tool-framework.ts";
 import { loadSupiConfigSectionForScope, type SupiConfigOptions } from "./config.ts";
 
 // ── Public types ───────────────────────────────────────────────────────────
 
+/** Model-facing text that PI adds to one registered tool's prompt surface. */
+export interface SuiPiToolPromptSurface {
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+}
+
 export type ToolPromptSurfaceDiagnosticCode =
   | "invalidPromptSurfaceConfig"
   | "invalidPromptSurfaceField"

package/node_modules/@mrclrchtr/supi-core/src/config.ts

@@ -1,7 +1,6 @@
 // supi-core config domain — config loading.
 export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
-  loadSectionConfig,
   loadSupiConfig,
   loadSupiConfigForScope,
   loadSupiConfigSectionForScope,

package/node_modules/@mrclrchtr/supi-core/src/context.ts

@@ -1,12 +1,4 @@
-// supi-core context domain — context messages, providers, and XML tags.
-export type { ContextMessageLike } from "./context/context-messages.ts";
-export {
-  findLastUserMessageIndex,
-  getContextToken,
-  getPromptContent,
-  pruneAndReorderContextMessages,
-  restorePromptContent,
-} from "./context/context-messages.ts";
+// supi-core context domain — context providers and XML tags.
 export type { ContextProvider } from "./context/context-provider-registry.ts";
 export {
   clearRegisteredContextProviders,

package/node_modules/@mrclrchtr/supi-core/src/debug-registry.ts

@@ -4,6 +4,9 @@
 // supi-debug extension owns policy/configuration and exposes events through a
 // command/tool while this module stays dependency-free for producers.
 
+// biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
+export * from "./debug-timing.ts";
+
 export type DebugLevel = "debug" | "info" | "warning" | "error";
 export type DebugAgentAccess = "off" | "sanitized" | "raw";
 export interface DebugRegistryConfig {
@@ -180,6 +183,11 @@ export function getDebugRegistryConfig(): DebugRegistryConfig {
   return cloneConfig(getState().config);
 }
 
+/** Return whether the Debug Registry currently retains producer events. */
+export function isDebugRegistryEnabled(): boolean {
+  return getState().config.enabled;
+}
+
 /** Best-effort redaction helper for data exposed through sanitized debug views. */
 export function redactDebugData<T>(value: T): T {
   return redactValue(value, 8) as T;

package/node_modules/@mrclrchtr/supi-core/src/debug-timing.ts

@@ -0,0 +1,107 @@
+import { performance } from "node:perf_hooks";
+import {
+  type DebugEvent,
+  type DebugEventInput,
+  isDebugRegistryEnabled,
+  recordDebugEvent,
+} from "./debug-registry.ts";
+
+/** Monotonic duration data added to a timed debug event. */
+export interface DebugTiming {
+  readonly durationMs: number;
+  readonly phasesMs: Readonly<Record<string, number>>;
+}
+
+/** Debug event input whose data can receive the reserved `timing` field. */
+export interface TimedDebugEventInput extends Omit<DebugEventInput, "data"> {
+  readonly data?: Readonly<Record<string, unknown>>;
+}
+
+/** Test seam for the monotonic clock used by a debug timer. */
+export interface DebugTimerOptions {
+  readonly now?: () => number;
+}
+
+/** Lazy timed-event input that is not evaluated when Debug is disabled. */
+export type TimedDebugEventFactory = () => TimedDebugEventInput;
+
+/** One-shot debug timer with optional sequential phase measurements. */
+export interface DebugTimer {
+  /** Whether this timer sampled Debug as enabled when it started. */
+  readonly enabled: boolean;
+  /** Finish the current phase and start the next unnamed interval. */
+  mark(phase: string): void;
+  /** Record one event. A second call returns `null` without recording another event. */
+  finish(
+    input: TimedDebugEventInput | TimedDebugEventFactory,
+    finalPhase?: string,
+  ): DebugEvent | null;
+}
+
+/**
+ * Start a monotonic timer for one debug event.
+ *
+ * Each `mark(name)` stores the interval since the previous mark. `finish()`
+ * stores the total duration and can name the final interval. Repeated phase
+ * names are accumulated. Event data reserves the `timing` field. When Debug is
+ * disabled at start, this returns a no-op timer and does not read the clock.
+ * Pass a factory to `finish()` to avoid event-data construction when disabled.
+ */
+export function startDebugTimer(options: DebugTimerOptions = {}): DebugTimer {
+  if (!isDebugRegistryEnabled()) return DISABLED_DEBUG_TIMER;
+  const now = options.now ?? performance.now.bind(performance);
+  const startedAt = now();
+  let previousAt = startedAt;
+  let finished = false;
+  const phases = new Map<string, number>();
+
+  const markAt = (phase: string, current: number): void => {
+    const name = phase.trim();
+    if (!name) return;
+    phases.set(name, (phases.get(name) ?? 0) + Math.max(0, current - previousAt));
+    previousAt = current;
+  };
+
+  return {
+    enabled: true,
+    mark(phase) {
+      if (finished) return;
+      markAt(phase, now());
+    },
+    finish(input, finalPhase) {
+      if (finished) return null;
+      if (!isDebugRegistryEnabled()) {
+        finished = true;
+        return null;
+      }
+      const completedAt = now();
+      if (finalPhase) markAt(finalPhase, completedAt);
+      finished = true;
+      const phasesMs = Object.fromEntries(
+        [...phases.entries()].map(([name, value]) => [name, duration(value)]),
+      );
+      const timing: DebugTiming = {
+        durationMs: duration(completedAt - startedAt),
+        phasesMs,
+      };
+      const eventInput = typeof input === "function" ? input() : input;
+      return recordDebugEvent({
+        ...eventInput,
+        data: { ...eventInput.data, timing },
+      });
+    },
+  };
+}
+
+const DISABLED_DEBUG_TIMER: DebugTimer = Object.freeze({
+  enabled: false,
+  mark() {},
+  finish() {
+    return null;
+  },
+});
+
+function duration(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.round(Math.max(0, value) * 10) / 10;
+}

package/node_modules/@mrclrchtr/supi-core/src/index.ts

@@ -1,6 +1,6 @@
 // supi-core — shared infrastructure for SuPi extensions.
-// Provides XML context tag wrapping, unified config system, context-message utilities,
-// settings registry for supi-wide TUI settings, and a shared tool-spec/registration framework.
+// Provides XML context tag wrapping, unified config, prompt-surface resolution,
+// and shared settings, reporting, and session utilities.
 //
 // Convenience barrel — re-exports all domain entry points.
 // For lighter imports, use one of the domain subpaths directly
@@ -21,16 +21,14 @@ export * from "./path.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./project.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./prompt-surface.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./report.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./session.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./settings.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./settings-ui.ts";
-// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./status-spinner.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./terminal.ts";
-// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./tool-framework.ts";

package/node_modules/@mrclrchtr/supi-core/src/settings/settings-registry.ts

@@ -1,35 +1,53 @@
-// Event-backed settings contribution types for SuPi extensions.
-//
-// Extensions contribute declarative settings sections through PI's shared
-// event bus. The public helper is registerDeclarativeSettings(pi, ...); this module
-// owns the internal collector protocol used by /supi-settings.
+// Event-backed settings module registration and collection.
 
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { ScopedFieldValue, SettingsFieldAction } from "./settings-schema.ts";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ScopedFieldValue, SettingsAction } from "./settings-schema.ts";
 
 export const SUPI_SETTINGS_COLLECT_EVENT = "supi:settings:collect";
 
 export type SettingsScope = "project" | "global";
 
-export interface SettingsSection {
-  /** Stable contribution identifier — e.g. "lsp", "claude-md". */
+/** Scope and PI runtime state supplied for each settings read. */
+export interface SettingsContext {
+  scope: SettingsScope;
+  cwd: string;
+  ctx?: ExtensionContext;
+}
+
+/** A resolved, source-aware settings view. */
+export interface SettingsSnapshot {
+  rows: ScopedFieldValue[];
+}
+
+/** One user action routed to its owning settings module. */
+export interface SettingsActionRequest extends SettingsContext {
+  fieldKey: string;
+  action: SettingsAction;
+}
+
+/** Optional user-facing result from a successful settings action. */
+export interface SettingsApplyResult {
+  notice?: {
+    message: string;
+    level: "info" | "warning" | "error";
+  };
+}
+
+/**
+ * Canonical settings interface consumed by `/supi-settings`.
+ *
+ * Reads are always asynchronous. Apply resolves only after durable writes and
+ * module-owned refresh work complete. Implementations throw on failed writes.
+ */
+export interface SettingsModule {
   id: string;
-  /** Human-readable label shown in the UI. */
   label: string;
-  /** Load current ScopedFieldValue[] for the given scope. */
-  loadValues: (scope: SettingsScope, cwd: string, ctx?: ExtensionContext) => ScopedFieldValue[];
-  /** Handle a user action on a field in the selected scope. */
-  handleAction: (
-    scope: SettingsScope,
-    cwd: string,
-    fieldKey: string,
-    action: SettingsFieldAction,
-    ctx?: ExtensionContext,
-  ) => void;
+  read(context: SettingsContext): Promise<SettingsSnapshot>;
+  apply(request: SettingsActionRequest): Promise<SettingsApplyResult>;
 }
 
 export interface SettingsContributionCollector {
-  add(section: SettingsSection): void;
+  add(module: SettingsModule): void;
 }
 
 export interface SettingsCollectionDiagnostic {
@@ -38,7 +56,7 @@ export interface SettingsCollectionDiagnostic {
 }
 
 export interface SettingsCollectionResult {
-  sections: SettingsSection[];
+  modules: SettingsModule[];
   diagnostics: SettingsCollectionDiagnostic[];
 }
 
@@ -56,21 +74,29 @@ export function isSettingsContributionCollector(
 export function createSettingsContributionCollector(): SettingsContributionCollector & {
   result(): SettingsCollectionResult;
 } {
-  const sections = new Map<string, SettingsSection>();
+  const modules = new Map<string, SettingsModule>();
   const diagnostics: SettingsCollectionDiagnostic[] = [];
 
   return {
-    add(section: SettingsSection): void {
-      if (sections.has(section.id)) {
+    add(module: SettingsModule): void {
+      if (modules.has(module.id)) {
         diagnostics.push({
           kind: "warning",
-          message: `Duplicate SuPi settings contribution "${section.id}"; using the last contribution.`,
+          message: `Duplicate SuPi settings contribution "${module.id}"; using the last contribution.`,
         });
       }
-      sections.set(section.id, section);
+      modules.set(module.id, module);
     },
     result(): SettingsCollectionResult {
-      return { sections: Array.from(sections.values()), diagnostics: [...diagnostics] };
+      return { modules: Array.from(modules.values()), diagnostics: [...diagnostics] };
     },
   };
 }
+
+/** Register one settings module during extension factory setup. */
+export function registerSettings(pi: ExtensionAPI, module: SettingsModule): void {
+  const dispose = pi.events.on(SUPI_SETTINGS_COLLECT_EVENT, (collector) => {
+    if (isSettingsContributionCollector(collector)) collector.add(module);
+  });
+  pi.on("session_shutdown", () => dispose());
+}