@mrclrchtr/supi-insights 2.0.6 → 2.1.0

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

@@ -39,10 +39,9 @@ Config file locations:
 
 ### Settings helpers
 
-- `registerSettings()` — register an arbitrary settings section
-- `registerConfigSettings()` — register a config-backed settings section with scoped persistence helpers
-- `registerSettingsCommand()` — register `/supi-settings`
-- `openSettingsOverlay()` — open the shared settings UI directly
+- `registerConfigSettings(pi, options)` — contribute a config-backed settings section with scoped persistence helpers
+- `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
 
 The built-in settings UI supports:
@@ -83,25 +82,34 @@ The built-in settings UI supports:
 ## Example
 
 ```ts
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { loadSupiConfig, registerConfigSettings, wrapExtensionContext } from "@mrclrchtr/supi-core/api";
 
-const config = loadSupiConfig("my-extension", process.cwd(), {
-  enabled: true,
-});
-
-registerConfigSettings({
-  id: "my-extension",
-  label: "My Extension",
-  section: "my-extension",
-  defaults: { enabled: true },
-  buildItems: () => [],
-  persistChange: () => {},
-});
-
-const message = wrapExtensionContext("my-extension", "hello", {
-  file: "CLAUDE.md",
-  turn: 1,
-});
+export default function myExtension(pi: ExtensionAPI) {
+  const defaults = { enabled: true };
+  const config = loadSupiConfig("my-extension", process.cwd(), defaults);
+
+  registerConfigSettings(pi, {
+    id: "my-extension",
+    label: "My Extension",
+    section: "my-extension",
+    defaults,
+    buildItems: (settings) => [
+      {
+        id: "enabled",
+        label: "Enabled",
+        currentValue: settings.enabled ? "on" : "off",
+        values: ["on", "off"],
+        configType: "boolean" as const,
+      },
+    ],
+  });
+
+  const message = wrapExtensionContext("my-extension", "hello", {
+    enabled: config.enabled,
+  });
+  void message;
+}
 ```
 
 ## Source

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "2.0.6",
+  "version": "2.1.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -70,6 +70,7 @@
     "./status-spinner": "./src/status-spinner.ts",
     "./terminal": "./src/terminal.ts",
     "./tool-framework": "./src/tool-framework.ts",
+    "./prompt-surface": "./src/prompt-surface.ts",
     "./types": "./src/types.ts"
   }
 }

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

@@ -1,14 +1,17 @@
-// Config-aware settings helper for SuPi config-backed settings sections.
-// Wraps registerSettings() and centralizes selected-scope loading + scoped persistence.
+// Config-aware settings contribution helper for SuPi packages.
 //
-// Setting items can declare a `configType` ("boolean" | "number" | "stringList")
-// to enable auto-generated persistChange. When all items have a configType,
-// the persistChange callback can be omitted.
+// Registers config-backed settings sections through PI's shared event bus so
+// /supi-settings can collect contributions from all loaded extensions without
+// relying on a shared supi-core module instance.
 
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { SettingItem } from "@earendil-works/pi-tui";
-import type { SettingsScope } from "../settings/settings-registry.ts";
-import { registerSettings } from "../settings/settings-registry.ts";
+import {
+  isSettingsContributionCollector,
+  type SettingsScope,
+  type SettingsSection,
+  SUPI_SETTINGS_COLLECT_EVENT,
+} from "../settings/settings-registry.ts";
 import { loadSupiConfigForScope, removeSupiConfigKey, writeSupiConfig } from "./config.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
@@ -22,22 +25,13 @@ import { loadSupiConfigForScope, removeSupiConfigKey, writeSupiConfig } from "./
  */
 export type ConfigSettingType = "boolean" | "number" | "stringList";
 
-/**
- * Extended setting item that can declare its config type for auto-generated
- * persistence handling.
- */
+/** Extended setting item that can declare its config type for persistence. */
 export interface ConfigSettingItem extends SettingItem {
-  /**
-   * When set, persistChange for this item is auto-generated.
-   * All items must declare a configType for auto-generation to activate.
-   */
+  /** Config value type used for auto-generated persistence. */
   configType?: ConfigSettingType;
 }
 
-/**
- * Helpers provided to the persistChange callback for writing or removing
- * scoped config values.
- */
+/** Helpers provided to persistChange for scoped SuPi config writes. */
 export interface ConfigSettingsHelpers {
   /** Write a key to the selected scope's config section. */
   set(key: string, value: unknown): void;
@@ -45,22 +39,23 @@ export interface ConfigSettingsHelpers {
   unset(key: string): void;
 }
 
+export interface ConfigSettingsPersistedChange {
+  scope: SettingsScope;
+  cwd: string;
+  settingId: string;
+  value: string;
+}
+
 export interface ConfigSettingsOptions<T> {
-  /** Extension identifier — e.g. "lsp", "claude-md" */
+  /** Settings contribution identifier — e.g. "lsp", "claude-md". */
   id: string;
-  /** Human-readable label shown in the UI */
+  /** Human-readable label shown in the UI. */
   label: string;
-  /** SuPi config section name — e.g. "lsp", "claude-md" */
+  /** SuPi config section name — e.g. "lsp", "claude-md". */
   section: string;
-  /** Default config values */
+  /** Default config values. */
   defaults: T;
-  /**
-   * Build SettingItem[] from scoped config. Called by loadValues.
-   *
-   * Items can include a `configType` property for auto-generated
-   * persistChange handling. When ALL items declare a configType,
-   * the `persistChange` callback can be omitted.
-   */
+  /** Build SettingItem[] from scoped config. */
   buildItems: (
     settings: T,
     scope: SettingsScope,
@@ -68,10 +63,10 @@ export interface ConfigSettingsOptions<T> {
     ctx?: ExtensionContext,
   ) => ConfigSettingItem[];
   /**
-   * Handle a settings change with scoped persistence helpers.
+   * Convert a UI value into scoped SuPi config writes.
    *
-   * Optional when all items returned by `buildItems` declare a `configType`.
-   * Required when any item lacks a `configType`.
+   * Optional when every item returned by `buildItems` declares `configType`.
+   * Required when any item lacks `configType`.
    */
   persistChange?: (
     scope: SettingsScope,
@@ -80,6 +75,8 @@ export interface ConfigSettingsOptions<T> {
     value: string,
     helpers: ConfigSettingsHelpers,
   ) => void;
+  /** Optional live runtime sync after successful persistence. */
+  afterPersist?: (change: ConfigSettingsPersistedChange) => void;
   /** Optional home directory for config resolution (testing). */
   homeDir?: string;
 }
@@ -128,23 +125,27 @@ function areAllItemsDeclarative(items: ConfigSettingItem[]): boolean {
   return items.length > 0 && items.every((i) => i.configType !== undefined);
 }
 
-// ── Registration ───────────────────────────────────────────────────────────
+function createHelpers<T>(options: ConfigSettingsOptions<T>, scope: SettingsScope, cwd: string) {
+  return {
+    set: (key: string, val: unknown) => {
+      writeSupiConfig(
+        { section: options.section, scope, cwd },
+        { [key]: val },
+        { homeDir: options.homeDir },
+      );
+    },
+    unset: (key: string) => {
+      removeSupiConfigKey({ section: options.section, scope, cwd }, key, {
+        homeDir: options.homeDir,
+      });
+    },
+  } satisfies ConfigSettingsHelpers;
+}
 
-/**
- * Register a config-backed settings section.
- *
- * Loads display values from the selected scope only (`defaults <- selected scope`)
- * instead of merged effective runtime config. Provides scoped `set` / `unset`
- * persistence helpers so extensions don't need to wire `writeSupiConfig` /
- * `removeSupiConfigKey` by hand.
- *
- * When every item returned by `buildItems` declares a `configType`, the
- * `persistChange` callback is optional and will be auto-generated.
- */
-export function registerConfigSettings<T>(options: ConfigSettingsOptions<T>): void {
+function toSettingsSection<T>(options: ConfigSettingsOptions<T>): SettingsSection {
   let cachedItems: ConfigSettingItem[] | undefined;
 
-  registerSettings({
+  return {
     id: options.id,
     label: options.label,
     loadValues: (scope, cwd, ctx) => {
@@ -157,32 +158,50 @@ export function registerConfigSettings<T>(options: ConfigSettingsOptions<T>): vo
       return items;
     },
     persistChange: (scope, cwd, settingId, value) => {
-      const helpers: ConfigSettingsHelpers = {
-        set: (key, val) => {
-          writeSupiConfig(
-            { section: options.section, scope, cwd },
-            { [key]: val },
-            { homeDir: options.homeDir },
-          );
-        },
-        unset: (key) => {
-          removeSupiConfigKey({ section: options.section, scope, cwd }, key, {
-            homeDir: options.homeDir,
-          });
-        },
-      };
-
-      // Use manual persistChange when provided
+      const helpers = createHelpers(options, scope, cwd);
+
       if (options.persistChange) {
         options.persistChange(scope, cwd, settingId, value, helpers);
-        return;
+      } else {
+        const items = cachedItems ?? options.buildItems(options.defaults, scope, cwd, undefined);
+        if (!areAllItemsDeclarative(items)) {
+          throw new Error(
+            `Settings contribution "${options.id}" needs persistChange or configType on every item.`,
+          );
+        }
+        autoPersistChange(settingId, value, helpers, items);
       }
 
-      // Auto-generate when all items are declarative
-      const items = cachedItems ?? options.buildItems(options.defaults, scope, cwd, undefined);
-      if (areAllItemsDeclarative(items)) {
-        autoPersistChange(settingId, value, helpers, items);
+      try {
+        options.afterPersist?.({ scope, cwd, settingId, value });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Saved setting, but live sync failed: ${message}`, { cause: error });
       }
     },
+  };
+}
+
+// ── Registration ───────────────────────────────────────────────────────────
+
+/**
+ * Register a config-backed settings contribution for `/supi-settings`.
+ *
+ * Contributions are collected through PI's process-local event bus. Call this
+ * during the extension factory function, not in async session handlers.
+ */
+export function registerConfigSettings<T>(
+  pi: ExtensionAPI,
+  options: ConfigSettingsOptions<T>,
+): void {
+  const section = toSettingsSection(options);
+  const dispose = pi.events.on(SUPI_SETTINGS_COLLECT_EVENT, (collector) => {
+    if (isSettingsContributionCollector(collector)) {
+      collector.add(section);
+    }
+  });
+
+  pi.on("session_shutdown", () => {
+    dispose();
   });
 }

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

@@ -21,6 +21,15 @@ function getProjectConfigPath(cwd: string): string {
   return path.join(cwd, PROJECT_CONFIG_DIR, CONFIG_FILE);
 }
 
+/** Return the SuPi config file path for one scope. */
+export function getSupiConfigPath(
+  scope: "global" | "project",
+  cwd: string,
+  options?: SupiConfigOptions,
+): string {
+  return scope === "global" ? getGlobalConfigPath(options?.homeDir) : getProjectConfigPath(cwd);
+}
+
 export function readJsonFile(filePath: string): Record<string, unknown> | null {
   let content: string;
   try {
@@ -95,15 +104,22 @@ export function loadSupiConfigForScope<T>(
   defaults: T,
   options: { scope: "global" | "project" } & SupiConfigOptions,
 ): T {
-  const config =
-    options.scope === "global"
-      ? readJsonFile(getGlobalConfigPath(options.homeDir))
-      : readJsonFile(getProjectConfigPath(cwd));
+  const config = readJsonFile(getSupiConfigPath(options.scope, cwd, { homeDir: options.homeDir }));
 
   const scopedSection = extractSection(config, section);
   return shallowMerge(defaults, scopedSection);
 }
 
+/** Load the raw object for one config section and one scope. */
+export function loadSupiConfigSectionForScope(
+  section: string,
+  cwd: string,
+  options: { scope: "global" | "project" } & SupiConfigOptions,
+): Record<string, unknown> | null {
+  const config = readJsonFile(getSupiConfigPath(options.scope, cwd, { homeDir: options.homeDir }));
+  return extractSection(config, section);
+}
+
 export interface SupiConfigLocation {
   section: string;
   scope: "global" | "project";
@@ -118,8 +134,7 @@ export function writeSupiConfig(
   value: Record<string, unknown>,
   options?: SupiConfigOptions,
 ): void {
-  const configPath =
-    loc.scope === "global" ? getGlobalConfigPath(options?.homeDir) : getProjectConfigPath(loc.cwd);
+  const configPath = getSupiConfigPath(loc.scope, loc.cwd, options);
 
   const dir = path.dirname(configPath);
   fs.mkdirSync(dir, { recursive: true });
@@ -142,8 +157,7 @@ export function removeSupiConfigKey(
   key: string,
   options?: SupiConfigOptions,
 ): void {
-  const configPath =
-    loc.scope === "global" ? getGlobalConfigPath(options?.homeDir) : getProjectConfigPath(loc.cwd);
+  const configPath = getSupiConfigPath(loc.scope, loc.cwd, options);
 
   const existing = readJsonFile(configPath);
   if (!existing) return;

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

@@ -0,0 +1,357 @@
+// Configurable tool prompt-surface overrides.
+//
+// Resolution order: package defaults ← global SuPi config ← trusted project SuPi config.
+// Project overrides are trust-gated; they require PI project trust and a PI-recognized
+// trust-requiring resource (e.g. .pi/settings.json).
+
+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 ───────────────────────────────────────────────────────────
+
+export type ToolPromptSurfaceDiagnosticCode =
+  | "invalidPromptSurfaceConfig"
+  | "invalidPromptSurfaceField"
+  | "projectPromptSurfaceIgnored";
+
+export interface ToolPromptSurfaceDiagnostic {
+  code: ToolPromptSurfaceDiagnosticCode;
+  scope: "global" | "project";
+  section: string;
+  toolName: string;
+  message: string;
+}
+
+export interface ResolveToolPromptSurfaceOptions extends SupiConfigOptions {
+  section: string;
+  toolName: string;
+  defaults: SuiPiToolPromptSurface;
+  ctx: Pick<ExtensionContext, "cwd" | "isProjectTrusted">;
+}
+
+export interface ResolveToolPromptSurfaceResult {
+  surface: SuiPiToolPromptSurface;
+  diagnostics: ToolPromptSurfaceDiagnostic[];
+}
+
+// ── Private types ──────────────────────────────────────────────────────────
+
+type PromptSurfaceField = keyof SuiPiToolPromptSurface;
+type PromptSurfaceScope = ToolPromptSurfaceDiagnostic["scope"];
+
+const PROMPT_SURFACE_FIELDS = new Set<string>(["description", "promptSnippet", "promptGuidelines"]);
+
+const PROMPT_SURFACE_DIAGNOSTICS_KEY = Symbol.for(
+  "@mrclrchtr/supi-core/tool-prompt-surface/notified-diagnostics",
+);
+
+// ── Resolution ─────────────────────────────────────────────────────────────
+
+/** Resolve a tool's model-facing prompt surface from defaults + SuPi config overrides. */
+export function resolveToolPromptSurface(
+  options: ResolveToolPromptSurfaceOptions,
+): ResolveToolPromptSurfaceResult {
+  const diagnostics: ToolPromptSurfaceDiagnostic[] = [];
+  let surface = clonePromptSurface(options.defaults);
+
+  const globalSection = loadSupiConfigSectionForScope(options.section, options.ctx.cwd, {
+    scope: "global",
+    homeDir: options.homeDir,
+  });
+  surface = applyPromptSurfaceScope(surface, options, "global", globalSection, diagnostics);
+
+  const projectSection = loadSupiConfigSectionForScope(options.section, options.ctx.cwd, {
+    scope: "project",
+    homeDir: options.homeDir,
+  });
+  const projectPromptSurface = getPromptSurfaceConfig(projectSection, options.toolName, {
+    diagnostics,
+    options,
+    scope: "project",
+  });
+
+  if (projectPromptSurface) {
+    const hasTrustMarker = hasTrustRequiringProjectResources(options.ctx.cwd);
+    const projectTrusted = options.ctx.isProjectTrusted();
+    if (hasTrustMarker && projectTrusted) {
+      surface = applyPromptSurfaceConfig(
+        surface,
+        options.defaults,
+        projectPromptSurface,
+        options,
+        "project",
+        diagnostics,
+      );
+    } else {
+      diagnostics.push({
+        code: "projectPromptSurfaceIgnored",
+        scope: "project",
+        section: options.section,
+        toolName: options.toolName,
+        message: hasTrustMarker
+          ? `Project prompt-surface overrides for ${options.toolName} were ignored because the project is not trusted in PI.`
+          : `Project prompt-surface overrides for ${options.toolName} were ignored because ${options.ctx.cwd}/.pi/supi/config.json is not PI trust-gated. Add .pi/settings.json and trust the project to enable them.`,
+      });
+    }
+  }
+
+  return { surface, diagnostics };
+}
+
+/** Notify prompt-surface diagnostics once per session/tool/diagnostic code. */
+export function notifyToolPromptSurfaceDiagnostics(
+  ctx: Pick<ExtensionContext, "sessionManager" | "ui">,
+  diagnostics: readonly ToolPromptSurfaceDiagnostic[],
+): void {
+  const globalRecord = globalThis as Record<symbol, Set<string> | undefined>;
+  const notified = globalRecord[PROMPT_SURFACE_DIAGNOSTICS_KEY] ?? new Set<string>();
+  globalRecord[PROMPT_SURFACE_DIAGNOSTICS_KEY] = notified;
+  const sessionId = ctx.sessionManager.getSessionId();
+
+  for (const diagnostic of diagnostics) {
+    const key = `${sessionId}:${diagnostic.section}:${diagnostic.toolName}:${diagnostic.code}`;
+    if (notified.has(key)) continue;
+    notified.add(key);
+    ctx.ui.notify(diagnostic.message, "warning");
+  }
+}
+
+// ── Scope helpers ──────────────────────────────────────────────────────────
+
+// biome-ignore lint/complexity/useMaxParams: resolver dispatch with diagnostics
+function applyPromptSurfaceScope(
+  current: SuiPiToolPromptSurface,
+  options: ResolveToolPromptSurfaceOptions,
+  scope: PromptSurfaceScope,
+  sectionConfig: Record<string, unknown> | null,
+  diagnostics: ToolPromptSurfaceDiagnostic[],
+): SuiPiToolPromptSurface {
+  const promptSurface = getPromptSurfaceConfig(sectionConfig, options.toolName, {
+    diagnostics,
+    options,
+    scope,
+  });
+  if (!promptSurface) return current;
+  return applyPromptSurfaceConfig(
+    current,
+    options.defaults,
+    promptSurface,
+    options,
+    scope,
+    diagnostics,
+  );
+}
+
+// biome-ignore lint/complexity/useMaxParams: per-scope config merger with diagnostics
+function applyPromptSurfaceConfig(
+  current: SuiPiToolPromptSurface,
+  defaults: SuiPiToolPromptSurface,
+  config: Record<string, unknown>,
+  options: ResolveToolPromptSurfaceOptions,
+  scope: PromptSurfaceScope,
+  diagnostics: ToolPromptSurfaceDiagnostic[],
+): SuiPiToolPromptSurface {
+  let next = clonePromptSurface(current);
+
+  for (const field of getResetFields(config.$reset, options, scope, diagnostics)) {
+    next = { ...next, [field]: clonePromptSurfaceField(defaults[field]) };
+  }
+
+  const description = getOptionalNonEmptyString(
+    config.description,
+    "description",
+    options,
+    scope,
+    diagnostics,
+  );
+  if (description !== undefined) next.description = description;
+
+  const promptSnippet = getOptionalNonEmptyString(
+    config.promptSnippet,
+    "promptSnippet",
+    options,
+    scope,
+    diagnostics,
+  );
+  if (promptSnippet !== undefined) next.promptSnippet = promptSnippet;
+
+  const promptGuidelines = getOptionalStringArray(
+    config.promptGuidelines,
+    "promptGuidelines",
+    options,
+    scope,
+    diagnostics,
+  );
+  if (promptGuidelines !== undefined) next.promptGuidelines = promptGuidelines;
+
+  const prepend = getOptionalStringArray(
+    config.prependPromptGuidelines,
+    "prependPromptGuidelines",
+    options,
+    scope,
+    diagnostics,
+  );
+  if (prepend !== undefined) next.promptGuidelines = [...prepend, ...next.promptGuidelines];
+
+  const append = getOptionalStringArray(
+    config.appendPromptGuidelines,
+    "appendPromptGuidelines",
+    options,
+    scope,
+    diagnostics,
+  );
+  if (append !== undefined) next.promptGuidelines = [...next.promptGuidelines, ...append];
+
+  return next;
+}
+
+// ── Config extraction ──────────────────────────────────────────────────────
+
+function getPromptSurfaceConfig(
+  sectionConfig: Record<string, unknown> | null,
+  toolName: string,
+  deps: {
+    diagnostics: ToolPromptSurfaceDiagnostic[];
+    options: ResolveToolPromptSurfaceOptions;
+    scope: PromptSurfaceScope;
+  },
+): Record<string, unknown> | null {
+  if (!sectionConfig) return null;
+  if (sectionConfig.tools === undefined) return null;
+  if (!isRecord(sectionConfig.tools)) {
+    pushInvalidConfig(deps, "tools must be an object.");
+    return null;
+  }
+  const toolConfig = sectionConfig.tools[toolName];
+  if (toolConfig === undefined) return null;
+  if (!isRecord(toolConfig)) {
+    pushInvalidConfig(deps, `tools.${toolName} must be an object.`);
+    return null;
+  }
+  if (toolConfig.promptSurface === undefined) return null;
+  if (!isRecord(toolConfig.promptSurface)) {
+    pushInvalidConfig(deps, `tools.${toolName}.promptSurface must be an object.`);
+    return null;
+  }
+  return toolConfig.promptSurface;
+}
+
+// ── Field validation ───────────────────────────────────────────────────────
+
+function getResetFields(
+  value: unknown,
+  options: ResolveToolPromptSurfaceOptions,
+  scope: PromptSurfaceScope,
+  diagnostics: ToolPromptSurfaceDiagnostic[],
+): PromptSurfaceField[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) {
+    pushInvalidField(options, scope, diagnostics, "$reset", "must be an array.");
+    return [];
+  }
+  const fields: PromptSurfaceField[] = [];
+  for (const item of value) {
+    if (typeof item === "string" && PROMPT_SURFACE_FIELDS.has(item)) {
+      fields.push(item as PromptSurfaceField);
+    } else {
+      pushInvalidField(
+        options,
+        scope,
+        diagnostics,
+        "$reset",
+        `contains unsupported field ${JSON.stringify(item)}.`,
+      );
+    }
+  }
+  return fields;
+}
+
+// biome-ignore lint/complexity/useMaxParams: validation helper with diagnostics
+function getOptionalNonEmptyString(
+  value: unknown,
+  field: string,
+  options: ResolveToolPromptSurfaceOptions,
+  scope: PromptSurfaceScope,
+  diagnostics: ToolPromptSurfaceDiagnostic[],
+): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value === "string" && value.length > 0) return value;
+  pushInvalidField(options, scope, diagnostics, field, "must be a non-empty string.");
+  return undefined;
+}
+
+// biome-ignore lint/complexity/useMaxParams: validation helper with diagnostics
+function getOptionalStringArray(
+  value: unknown,
+  field: string,
+  options: ResolveToolPromptSurfaceOptions,
+  scope: PromptSurfaceScope,
+  diagnostics: ToolPromptSurfaceDiagnostic[],
+): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+    return [...value];
+  }
+  pushInvalidField(options, scope, diagnostics, field, "must be an array of strings.");
+  return undefined;
+}
+
+// ── Diagnostics ────────────────────────────────────────────────────────────
+
+function pushInvalidConfig(
+  deps: {
+    diagnostics: ToolPromptSurfaceDiagnostic[];
+    options: ResolveToolPromptSurfaceOptions;
+    scope: PromptSurfaceScope;
+  },
+  detail: string,
+): void {
+  deps.diagnostics.push({
+    // biome-ignore lint/security/noSecrets: false positive on string constant
+    code: "invalidPromptSurfaceConfig",
+    scope: deps.scope,
+    section: deps.options.section,
+    toolName: deps.options.toolName,
+    message: `Invalid prompt-surface config for ${deps.options.section}.${deps.options.toolName}: ${detail}`,
+  });
+}
+
+// biome-ignore lint/complexity/useMaxParams: diagnostics utility with many fields
+function pushInvalidField(
+  options: ResolveToolPromptSurfaceOptions,
+  scope: PromptSurfaceScope,
+  diagnostics: ToolPromptSurfaceDiagnostic[],
+  field: string,
+  detail: string,
+): void {
+  diagnostics.push({
+    // biome-ignore lint/security/noSecrets: false positive on string constant
+    code: "invalidPromptSurfaceField",
+    scope,
+    section: options.section,
+    toolName: options.toolName,
+    message: `Invalid prompt-surface field ${field} for ${options.section}.${options.toolName}: ${detail}`,
+  });
+}
+
+// ── Cloning ────────────────────────────────────────────────────────────────
+
+function clonePromptSurface(surface: SuiPiToolPromptSurface): SuiPiToolPromptSurface {
+  return {
+    description: surface.description,
+    promptSnippet: surface.promptSnippet,
+    promptGuidelines: [...surface.promptGuidelines],
+  };
+}
+
+function clonePromptSurfaceField<T extends string | string[]>(value: T): T {
+  return (Array.isArray(value) ? [...value] : value) as T;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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

@@ -0,0 +1,4 @@
+// supi-core prompt-surface — configurable tool prompt-surface resolver (package boundary for @mrclrchtr/supi-core/prompt-surface).
+
+// biome-ignore lint/performance/noReExportAll: intentional barrel
+export * from "./config/prompt-surface.ts";

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

@@ -9,7 +9,7 @@ export function registerSettingsCommand(pi: ExtensionAPI): void {
   pi.registerCommand("supi-settings", {
     description: "Manage SuPi extension settings",
     handler: async (_args, ctx) => {
-      openSettingsOverlay(ctx);
+      openSettingsOverlay(pi, ctx);
     },
   });
 }

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

@@ -1,48 +1,70 @@
-// Settings registry for SuPi extensions.
+// Event-backed settings contribution types for SuPi extensions.
 //
-// Extensions declare their settings via `registerSettings()` during their
-// factory function. The generic settings UI reads them via `getRegisteredSettings()`.
+// Extensions contribute config-backed settings sections through PI's shared
+// event bus. The public helper is registerConfigSettings(pi, ...); this module
+// owns the internal collector protocol used by /supi-settings.
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { SettingItem } from "@earendil-works/pi-tui";
-import { createRegistry } from "../registry-utils.ts";
+
+export const SUPI_SETTINGS_COLLECT_EVENT = "supi:settings:collect";
 
 export type SettingsScope = "project" | "global";
 
 export interface SettingsSection {
-  /** Extension identifier — e.g. "lsp", "claude-md" */
+  /** Stable contribution identifier — e.g. "lsp", "claude-md". */
   id: string;
-  /** Human-readable label shown in the UI */
+  /** Human-readable label shown in the UI. */
   label: string;
-  /** Load current SettingItem[] for the given scope */
+  /** Load current SettingItem[] for the given scope. */
   loadValues: (scope: SettingsScope, cwd: string, ctx?: ExtensionContext) => SettingItem[];
-  /** Persist a change back to config */
-  persistChange: (
-    scope: SettingsScope,
-    cwd: string,
-    settingId: string,
-    value: string,
-    ctx?: ExtensionContext,
-  ) => void;
+  /** Persist a UI value back to SuPi config. */
+  persistChange: (scope: SettingsScope, cwd: string, settingId: string, value: string) => void;
 }
 
-const registry = createRegistry<SettingsSection>("settings-registry");
+export interface SettingsContributionCollector {
+  add(section: SettingsSection): void;
+}
 
-/**
- * Register a settings section for an extension.
- * Call during the extension factory function (not async handlers).
- * Duplicate ids replace the previous registration.
- */
-export function registerSettings(section: SettingsSection): void {
-  registry.register(section.id, section);
+export interface SettingsCollectionDiagnostic {
+  kind: "warning";
+  message: string;
 }
 
-/** Get all registered settings sections in registration order. */
-export function getRegisteredSettings(): SettingsSection[] {
-  return registry.getAll();
+export interface SettingsCollectionResult {
+  sections: SettingsSection[];
+  diagnostics: SettingsCollectionDiagnostic[];
 }
 
-/** Clear the registry — used by tests. */
-export function clearRegisteredSettings(): void {
-  registry.clear();
+export function isSettingsContributionCollector(
+  value: unknown,
+): value is SettingsContributionCollector {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { add?: unknown }).add === "function"
+  );
+}
+
+/** Create a collector with last-wins duplicate handling and warning diagnostics. */
+export function createSettingsContributionCollector(): SettingsContributionCollector & {
+  result(): SettingsCollectionResult;
+} {
+  const sections = new Map<string, SettingsSection>();
+  const diagnostics: SettingsCollectionDiagnostic[] = [];
+
+  return {
+    add(section: SettingsSection): void {
+      if (sections.has(section.id)) {
+        diagnostics.push({
+          kind: "warning",
+          message: `Duplicate SuPi settings contribution "${section.id}"; using the last contribution.`,
+        });
+      }
+      sections.set(section.id, section);
+    },
+    result(): SettingsCollectionResult {
+      return { sections: Array.from(sections.values()), diagnostics: [...diagnostics] };
+    },
+  };
 }

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

@@ -3,7 +3,7 @@
 // Uses pi-tui's SettingsList with scope toggle (Tab), extension grouping,
 // and search. Each extension declares its settings via registerSettings().
 
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getSettingsListTheme } from "@earendil-works/pi-coding-agent";
 import {
   Container,
@@ -19,9 +19,11 @@ import {
 } from "@earendil-works/pi-tui";
 import { getSelectableModels } from "../model-selection.ts";
 import {
-  getRegisteredSettings,
+  createSettingsContributionCollector,
+  type SettingsCollectionDiagnostic,
   type SettingsScope,
   type SettingsSection,
+  SUPI_SETTINGS_COLLECT_EVENT,
 } from "./settings-registry.ts";
 
 // ── Input submenu component ──────────────────────────────────
@@ -73,9 +75,15 @@ export function createInputSubmenu(
 
 // ── Types ────────────────────────────────────────────────────
 
+interface OverlayStatus {
+  kind: "warning" | "error";
+  message: string;
+}
+
 interface OverlayState {
   scope: SettingsScope;
   cwd: string;
+  status?: OverlayStatus;
 }
 
 // ── Pure helpers ─────────────────────────────────────────────
@@ -117,10 +125,27 @@ function findSectionAndId(
   return { section, itemId };
 }
 
+function collectSettingsSections(pi: ExtensionAPI) {
+  const collector = createSettingsContributionCollector();
+  pi.events.emit(SUPI_SETTINGS_COLLECT_EVENT, collector);
+  return collector.result();
+}
+
+function latestStatus(diagnostics: SettingsCollectionDiagnostic[]): OverlayStatus | undefined {
+  const latest = diagnostics.at(-1);
+  return latest ? { kind: latest.kind, message: latest.message } : undefined;
+}
+
+function formatSettingsError(settingId: string, error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return `Could not save SuPi setting "${settingId}": ${message}`;
+}
+
 // ── Component ────────────────────────────────────────────────
 
 interface SettingsOverlayDeps {
   ctx: ExtensionContext;
+  sections: SettingsSection[];
   state: OverlayState;
   container: Container;
   settingsList: SettingsList | null;
@@ -130,22 +155,23 @@ interface SettingsOverlayDeps {
 }
 
 function createSettingsList(deps: SettingsOverlayDeps): SettingsList {
-  const sections = getRegisteredSettings();
-  const items = buildFlatItems(sections, deps.state.scope, deps.state.cwd, deps.ctx);
+  const items = buildFlatItems(deps.sections, deps.state.scope, deps.state.cwd, deps.ctx);
   const onChange = (flatId: string, newValue: string) => {
-    const found = findSectionAndId(sections, flatId);
-    if (found) {
-      found.section.persistChange(
-        deps.state.scope,
-        deps.state.cwd,
-        found.itemId,
-        newValue,
-        deps.ctx,
-      );
+    const found = findSectionAndId(deps.sections, flatId);
+    try {
+      if (found) {
+        found.section.persistChange(deps.state.scope, deps.state.cwd, found.itemId, newValue);
+        deps.state.status = undefined;
+      }
+    } catch (error) {
+      deps.state.status = {
+        kind: "error",
+        message: formatSettingsError(found?.itemId ?? flatId, error),
+      };
     }
     // Re-read all values to reflect persisted changes, but keep the list
     // instance (and its selectedIndex) intact.
-    const updatedItems = buildFlatItems(sections, deps.state.scope, deps.state.cwd, deps.ctx);
+    const updatedItems = buildFlatItems(deps.sections, deps.state.scope, deps.state.cwd, deps.ctx);
     for (const updated of updatedItems) {
       const existing = items.find((i) => i.id === updated.id);
       if (existing && existing.currentValue !== updated.currentValue) {
@@ -171,6 +197,7 @@ function rebuildSettingsList(deps: SettingsOverlayDeps): SettingsList {
 
   deps.container.clear();
   deps.container.addChild(createHeaderComponent(deps));
+  deps.container.addChild(createStatusComponent(deps));
   deps.container.addChild(settingsList);
 
   return settingsList;
@@ -188,6 +215,20 @@ function createHeaderComponent(deps: SettingsOverlayDeps): Text {
   return headerText;
 }
 
+function createStatusComponent(deps: SettingsOverlayDeps): {
+  render: () => string[];
+  invalidate: () => void;
+} {
+  return {
+    render: () => {
+      const status = deps.state.status;
+      if (!status) return [];
+      return [deps.theme.fg(status.kind, status.message)];
+    },
+    invalidate: () => {},
+  };
+}
+
 function handleScopeToggle(deps: SettingsOverlayDeps): void {
   deps.state.scope = deps.state.scope === "project" ? "global" : "project";
   rebuildSettingsList(deps);
@@ -288,19 +329,24 @@ function buildModelItems(ctx?: ExtensionContext): SelectItem[] {
 
 // ── Entry point ──────────────────────────────────────────────
 
-export function openSettingsOverlay(ctx: ExtensionContext): void {
-  const sections = getRegisteredSettings();
-  if (sections.length === 0) {
+export function openSettingsOverlay(pi: ExtensionAPI, ctx: ExtensionContext): void {
+  const collection = collectSettingsSections(pi);
+  if (collection.sections.length === 0) {
     ctx.ui.notify("No settings registered by SuPi extensions", "info");
     return;
   }
 
   void ctx.ui.custom<void>((tui, theme, _kb, done) => {
-    const state: OverlayState = { scope: "project", cwd: ctx.cwd };
+    const state: OverlayState = {
+      scope: "project",
+      cwd: ctx.cwd,
+      status: latestStatus(collection.diagnostics),
+    };
     const container = new Container();
 
     const deps: SettingsOverlayDeps = {
       ctx,
+      sections: collection.sections,
       state,
       container,
       settingsList: null,

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

@@ -1,9 +1,15 @@
-// supi-core settings domain — settings registry (lightweight, type-only pi-tui import).
+// supi-core settings domain — event-backed settings contribution types and command wiring.
 
 export { registerSettingsCommand } from "./settings/settings-command.ts";
-export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
+export type {
+  SettingsCollectionDiagnostic,
+  SettingsCollectionResult,
+  SettingsContributionCollector,
+  SettingsScope,
+  SettingsSection,
+} from "./settings/settings-registry.ts";
 export {
-  clearRegisteredSettings,
-  getRegisteredSettings,
-  registerSettings,
+  createSettingsContributionCollector,
+  isSettingsContributionCollector,
+  SUPI_SETTINGS_COLLECT_EVENT,
 } from "./settings/settings-registry.ts";

package/node_modules/@mrclrchtr/supi-core/src/tool-framework.ts

@@ -53,6 +53,16 @@ export function derivePromptSurface(spec: SuiPiToolSpec): SuiPiToolPromptSurface
   };
 }
 
+// Re-export prompt-surface types (implemented in config/prompt-surface.ts)
+export {
+  notifyToolPromptSurfaceDiagnostics,
+  type ResolveToolPromptSurfaceOptions,
+  type ResolveToolPromptSurfaceResult,
+  resolveToolPromptSurface,
+  type ToolPromptSurfaceDiagnostic,
+  type ToolPromptSurfaceDiagnosticCode,
+} from "./config/prompt-surface.ts";
+
 // ---------------------------------------------------------------------------
 // Registration
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-insights",
-  "version": "2.0.6",
+  "version": "2.1.0",
   "description": "SuPi Insights extension — generate usage reports analyzing your PI sessions",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,7 @@
   ],
   "dependencies": {
     "diff": "^9.0.0",
-    "@mrclrchtr/supi-core": "2.0.6"
+    "@mrclrchtr/supi-core": "2.1.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/html.ts

@@ -56,7 +56,7 @@ function renderProjectAreasHtml(insights: InsightResults): string {
       insights.projectAreas as
         | { areas?: Array<{ name: string; sessionCount: number; description: string }> }
         | undefined
-    )?.areas || [];
+    )?.areas ?? [];
 
   if (projectAreas.length === 0) return "";
 

package/src/insights.ts

@@ -76,7 +76,7 @@ function getConfig(cwd: string): InsightsConfig {
 
 export default function insightsExtension(pi: ExtensionAPI) {
   // Register config-backed settings for /supi-settings
-  registerConfigSettings<InsightsConfig>({
+  registerConfigSettings<InsightsConfig>(pi, {
     id: "insights",
     label: "Insights",
     section: "insights",