@mrclrchtr/supi-insights 1.10.0 → 1.11.0

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -19,11 +19,15 @@
     "!__tests__"
   ],
   "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
   "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
     "@earendil-works/pi-coding-agent": {
       "optional": true
     },
@@ -40,8 +44,10 @@
     "./config": "./src/config.ts",
     "./context": "./src/context.ts",
     "./debug": "./src/debug-registry.ts",
+    "./llm": "./src/llm.ts",
     "./package.json": "./package.json",
     "./path": "./src/path.ts",
+    "./progress-widget": "./src/progress-widget.ts",
     "./project": "./src/project.ts",
     "./session": "./src/session.ts",
     "./settings": "./src/settings.ts",

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

@@ -13,6 +13,8 @@ export * from "./context.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./debug-registry.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./llm.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./path.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./project.ts";

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

@@ -1,11 +1,42 @@
 // Config-aware settings helper for SuPi config-backed settings sections.
 // Wraps registerSettings() and centralizes selected-scope loading + scoped persistence.
+//
+// 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.
 
 import type { SettingItem } from "@earendil-works/pi-tui";
 import type { SettingsScope } from "../settings/settings-registry.ts";
 import { registerSettings } from "../settings/settings-registry.ts";
 import { loadSupiConfigForScope, removeSupiConfigKey, writeSupiConfig } from "./config.ts";
 
+// ── Types ──────────────────────────────────────────────────────────────────
+
+/**
+ * Supported config value types for declarative persistChange.
+ *
+ * - `"boolean"`: maps "on" → true, "off" → false
+ * - `"number"`: parses integer via Number.parseInt, falls back to unset on invalid
+ * - `"stringList"`: splits on comma, trims whitespace, unsets on empty
+ */
+export type ConfigSettingType = "boolean" | "number" | "stringList";
+
+/**
+ * Extended setting item that can declare its config type for auto-generated
+ * persistence handling.
+ */
+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.
+   */
+  configType?: ConfigSettingType;
+}
+
+/**
+ * Helpers provided to the persistChange callback for writing or removing
+ * scoped config values.
+ */
 export interface ConfigSettingsHelpers {
   /** Write a key to the selected scope's config section. */
   set(key: string, value: unknown): void;
@@ -22,10 +53,21 @@ export interface ConfigSettingsOptions<T> {
   section: string;
   /** Default config values */
   defaults: T;
-  /** Build SettingItem[] from scoped config. Called by loadValues. */
-  buildItems: (settings: T, scope: SettingsScope, cwd: string) => SettingItem[];
-  /** Handle a settings change with scoped persistence helpers. */
-  persistChange: (
+  /**
+   * 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.
+   */
+  buildItems: (settings: T, scope: SettingsScope, cwd: string) => ConfigSettingItem[];
+  /**
+   * Handle a settings change with scoped persistence helpers.
+   *
+   * Optional when all items returned by `buildItems` declare a `configType`.
+   * Required when any item lacks a `configType`.
+   */
+  persistChange?: (
     scope: SettingsScope,
     cwd: string,
     settingId: string,
@@ -36,6 +78,52 @@ export interface ConfigSettingsOptions<T> {
   homeDir?: string;
 }
 
+// ── Auto-generated persistChange ───────────────────────────────────────────
+
+function autoPersistChange(
+  settingId: string,
+  value: string,
+  helpers: ConfigSettingsHelpers,
+  items: ConfigSettingItem[],
+): void {
+  const item = items.find((i) => i.id === settingId);
+  if (!item?.configType) return;
+
+  switch (item.configType) {
+    case "boolean": {
+      helpers.set(settingId, value === "on");
+      break;
+    }
+    case "number": {
+      const num = Number.parseInt(value, 10);
+      if (Number.isFinite(num) && num > 0) {
+        helpers.set(settingId, num);
+      } else {
+        helpers.unset(settingId);
+      }
+      break;
+    }
+    case "stringList": {
+      const names = value
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+      if (names.length > 0) {
+        helpers.set(settingId, names);
+      } else {
+        helpers.unset(settingId);
+      }
+      break;
+    }
+  }
+}
+
+function areAllItemsDeclarative(items: ConfigSettingItem[]): boolean {
+  return items.length > 0 && items.every((i) => i.configType !== undefined);
+}
+
+// ── Registration ───────────────────────────────────────────────────────────
+
 /**
  * Register a config-backed settings section.
  *
@@ -43,8 +131,13 @@ export interface ConfigSettingsOptions<T> {
  * 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 {
+  let cachedItems: ConfigSettingItem[] | undefined;
+
   registerSettings({
     id: options.id,
     label: options.label,
@@ -53,7 +146,9 @@ export function registerConfigSettings<T>(options: ConfigSettingsOptions<T>): vo
         scope,
         homeDir: options.homeDir,
       });
-      return options.buildItems(settings, scope, cwd);
+      const items = options.buildItems(settings, scope, cwd);
+      cachedItems = items;
+      return items;
     },
     persistChange: (scope, cwd, settingId, value) => {
       const helpers: ConfigSettingsHelpers = {
@@ -70,7 +165,18 @@ export function registerConfigSettings<T>(options: ConfigSettingsOptions<T>): vo
           });
         },
       };
-      options.persistChange(scope, cwd, settingId, value, helpers);
+
+      // Use manual persistChange when provided
+      if (options.persistChange) {
+        options.persistChange(scope, cwd, settingId, value, helpers);
+        return;
+      }
+
+      // Auto-generate when all items are declarative
+      const items = cachedItems ?? options.buildItems(options.defaults, scope, cwd);
+      if (areAllItemsDeclarative(items)) {
+        autoPersistChange(settingId, value, helpers, items);
+      }
     },
   });
 }

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

@@ -184,3 +184,23 @@ 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/llm.ts

@@ -0,0 +1,211 @@
+import { complete } from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TSchema } from "typebox";
+import { Value } from "typebox/value";
+
+// Shared LLM utilities for SuPi extensions.
+//
+// Provides retry logic, structured LLM call helpers, and other
+// common patterns for extensions that interact with AI models.
+
+/**
+ * Options for {@link withRetry}.
+ */
+export interface WithRetryOptions {
+  /** Maximum number of retry attempts after the initial call. Default: 2 */
+  retries?: number;
+  /** Base delay in milliseconds for exponential backoff. Default: 1000 */
+  baseDelayMs?: number;
+  /** AbortSignal to cancel retry loops. */
+  signal?: AbortSignal;
+  /** Called with each failed attempt's attempt index and error. */
+  logger?: (attempt: number, error: unknown) => void;
+  /** Called before each retry delay with attempt index and computed delay. */
+  onRetry?: (attempt: number, delayMs: number) => void;
+}
+
+/**
+ * Attempt an async operation with retries and exponential backoff.
+ *
+ * If the signal is already aborted on entry, the operation is skipped entirely.
+ * If the signal aborts during a delay, the delay is cancelled immediately.
+ *
+ * @param fn - The async operation to retry.
+ * @param options - Optional configuration for retries, backoff, signal, and callbacks.
+ * @returns The result on success, or `null` if all attempts fail or the signal aborts.
+ */
+/**
+ * Create a promise that resolves after `ms` milliseconds, or rejects if
+ * the signal fires before the timeout elapses.
+ */
+function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    if (signal) {
+      const onAbort = () => {
+        clearTimeout(timer);
+        reject(new DOMException("Aborted", "AbortError"));
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+}
+
+/**
+ * Attempt an async operation with retries and exponential backoff.
+ *
+ * If the signal is already aborted on entry, the operation is skipped entirely.
+ * If the signal aborts during a delay, the delay is cancelled immediately.
+ *
+ * @param fn - The async operation to retry.
+ * @param options - Optional configuration for retries, backoff, signal, and callbacks.
+ * @returns The result on success, or `null` if all attempts fail or the signal aborts.
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options?: WithRetryOptions,
+): Promise<T | null> {
+  const { retries = 2, baseDelayMs = 1000, signal, logger, onRetry } = options ?? {};
+
+  if (signal?.aborted) return null;
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      logger?.(attempt, err);
+      if (attempt >= retries || signal?.aborted) continue;
+
+      const delayMs = baseDelayMs * 2 ** attempt;
+      onRetry?.(attempt, delayMs);
+
+      try {
+        await delay(delayMs, signal);
+      } catch {
+        // delay() only rejects on abort
+        return null;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Extract and validate JSON from LLM response content blocks.
+ *
+ * Finds the first JSON object `{...}` in the combined text content,
+ * parses it, and validates against a TypeBox schema.
+ *
+ * @param content - The LLM response content blocks.
+ * @param schema - TypeBox schema to validate against.
+ * @returns The parsed and validated result, or `null` if extraction or validation fails.
+ */
+export function extractJsonFromResponse<T extends TSchema>(
+  content: ReadonlyArray<{ type: string; text?: string }>,
+  schema: T,
+): { parsed: import("typebox").Static<T> } | null {
+  const text = content
+    .filter((c): c is { type: "text"; text: string } => c.type === "text")
+    .map((c) => c.text)
+    .join("");
+
+  const jsonMatch = text.match(/\{[\s\S]*\}/);
+  if (!jsonMatch) return null;
+
+  try {
+    const parsed = JSON.parse(jsonMatch[0]);
+    if (Value.Check(schema, parsed)) {
+      return { parsed } as { parsed: import("typebox").Static<T> };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// ── callWithJsonResponse ───────────────────────────────────────────────────
+
+/**
+ * Options for {@link callWithJsonResponse}.
+ */
+export interface CallWithJsonResponseOptions {
+  /** The prompt to send to the LLM. */
+  prompt: string;
+  /** Optional data context appended to the prompt. */
+  dataContext?: string;
+  /** Maximum tokens for the response. Default: 4096 */
+  maxTokens?: number;
+  /** System prompt for the LLM call. Default: "" */
+  systemPrompt?: string;
+  /** Number of retries for the LLM call. Default: 2 */
+  retries?: number;
+}
+
+/**
+ * Call the LLM with a prompt and validate the JSON response against a TypeBox schema.
+ *
+ * Handles model resolution, auth, retry via `withRetry`, text extraction,
+ * JSON regex matching, and TypeBox validation.
+ *
+ * Returns `null` when:
+ * - No model is available
+ * - All retries fail
+ * - Response contains no valid JSON
+ * - JSON doesn't match the schema
+ * - The request is aborted
+ *
+ * @param ctx - The extension context for model resolution and auth.
+ * @param options - Call options including prompt, schema, and retry config.
+ * @param schema - TypeBox schema to validate the JSON response against.
+ * @returns The parsed and validated result, or `null`.
+ */
+export async function callWithJsonResponse<T extends TSchema>(
+  ctx: ExtensionContext,
+  options: CallWithJsonResponseOptions,
+  schema: T,
+): Promise<{ parsed: import("typebox").Static<T> } | null> {
+  const { prompt, dataContext, maxTokens = 4096, systemPrompt = "", retries = 2 } = options;
+
+  const model = ctx.model ?? ctx.modelRegistry.getAvailable()[0] ?? null;
+  if (!model) return null;
+
+  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+  if (!auth.ok || !auth.apiKey) return null;
+
+  const fullPrompt = dataContext
+    ? `${prompt}
+
+DATA:
+${dataContext}`
+    : prompt;
+
+  const response = await withRetry(
+    async () => {
+      return complete(
+        model,
+        {
+          systemPrompt,
+          messages: [
+            {
+              role: "user",
+              content: [{ type: "text", text: fullPrompt }],
+              timestamp: Date.now(),
+            },
+          ],
+        },
+        {
+          apiKey: auth.apiKey,
+          headers: auth.headers,
+          signal: ctx.signal,
+          maxTokens,
+        },
+      );
+    },
+    { retries, baseDelayMs: 1000, signal: ctx.signal },
+  );
+
+  if (!response) return null;
+
+  return extractJsonFromResponse(response.content, schema);
+}

package/node_modules/@mrclrchtr/supi-core/src/progress-widget.ts

@@ -0,0 +1,108 @@
+// Generic progress widget for SuPi long-running operations.
+//
+// Provides a TUI-based progress display with animated loader, turn counts,
+// tool usage, and activity descriptions.
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { CancellableLoader, Container, Text } from "@earendil-works/pi-tui";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+/** Progress state for widget display, compatible with child-session updates. */
+export interface WidgetProgress {
+  /** Number of agent turns completed. */
+  turns: number;
+  /** Number of tool executions started. */
+  toolUses: number;
+  /** Human-readable active tool descriptions. */
+  activities: string[];
+  /** Token usage stats, if available. */
+  tokens?: { input: number; output: number; total: number };
+}
+
+// ── Widget ─────────────────────────────────────────────────────────────────
+
+/**
+ * TUI progress widget for long-running operations.
+ *
+ * Shows an animated loader, turn count, tool uses, token count, and any active
+ * tool descriptions while the child session or operation is running.
+ */
+export class ProgressWidget extends Container {
+  private message: string;
+  private progress: WidgetProgress = { turns: 0, toolUses: 0, activities: [] };
+  private loader: CancellableLoader;
+  private tui: { requestRender(): void };
+  private theme: Theme;
+
+  constructor(tui: { requestRender(): void }, theme: Theme, message: string) {
+    super();
+    this.tui = tui;
+    this.theme = theme;
+    this.message = message;
+    this.loader = new CancellableLoader(
+      tui as ConstructorParameters<typeof CancellableLoader>[0],
+      (text: string) => theme.fg("accent", text),
+      (text: string) => theme.fg("muted", text),
+      message,
+    );
+
+    this.renderContent();
+  }
+
+  /** AbortSignal that fires when the user presses Escape. */
+  get signal(): AbortSignal {
+    return this.loader.signal;
+  }
+
+  /** Callback invoked when the user presses Escape. */
+  set onAbort(fn: (() => void) | undefined) {
+    this.loader.onAbort = fn;
+  }
+
+  /** Delegate keyboard input to the loader. */
+  handleInput(data: string): void {
+    this.loader.handleInput(data);
+  }
+
+  /** Update progress state and request a re-render. */
+  updateProgress(progress: WidgetProgress): void {
+    this.progress = progress;
+    this.renderContent();
+    this.tui.requestRender();
+  }
+
+  /** Clean up the widget. */
+  dispose(): void {
+    this.loader.dispose();
+  }
+
+  private renderContent(): void {
+    this.clear();
+
+    const stats: string[] = [];
+    if (this.progress.turns > 0) stats.push(`⟳${this.progress.turns}`);
+    if (this.progress.toolUses > 0) stats.push(`${this.progress.toolUses} tool uses`);
+    if (this.progress.tokens) stats.push(`${formatTokens(this.progress.tokens.total)} tokens`);
+
+    const loaderMessage =
+      stats.length > 0 ? `${this.message} · ${stats.join(" · ")}` : this.message;
+
+    this.loader.setMessage(loaderMessage);
+    this.addChild(this.loader);
+
+    if (this.progress.activities.length > 0) {
+      this.addChild(
+        new Text(this.theme.fg("dim", `  ⎿  ${this.progress.activities.join(", ")}…`), 1, 0),
+      );
+    }
+  }
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function formatTokens(count: number): string {
+  if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
+  if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
+  return String(count);
+}

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

@@ -8,9 +8,11 @@ import type {
   AgentToolResult,
   AgentToolUpdateCallback,
   ExtensionAPI,
+  ExtensionCommandContext,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { type TSchema, Type } from "typebox";
+import { ProgressWidget, type WidgetProgress } from "./progress-widget.ts";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -114,3 +116,67 @@ export const SymbolParam = Type.String({
 
 /** Maximum results to return. */
 export const MaxResultsParam = Type.Number({ description: "Maximum results to return" });
+
+// ---------------------------------------------------------------------------
+// Progress widget runner
+// ---------------------------------------------------------------------------
+
+/**
+ * Run an async operation with a live TUI progress widget.
+ *
+ * Automatically manages:
+ * - The {@link ProgressWidget} lifecycle
+ * - `supi:working:start` / `supi:working:end` events for tab-spinner integration
+ * - Abort signal handling
+ * - Error catching (returns `null` on failure)
+ *
+ * Falls back to running without a widget when `ctx.hasUI` is false.
+ *
+ * @param pi - The extension API (for event emission).
+ * @param ctx - The command context (for UI access and hasUI check).
+ * @param title - The progress widget title.
+ * @param runner - Async function that receives (signal, onProgress).
+ * @returns The runner result, or `null` on cancel/error.
+ */
+export async function runWithProgressWidget<T>(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  title: string,
+  runner: (signal: AbortSignal, onProgress: (p: WidgetProgress) => void) => Promise<T>,
+): Promise<T | null> {
+  if (!ctx.hasUI) {
+    // No UI — run without progress widget but still emit working events
+    pi.events.emit("supi:working:start", { source: "supi-core" });
+    try {
+      return await runner(new AbortController().signal, () => {});
+    } catch {
+      return null;
+    } finally {
+      pi.events.emit("supi:working:end", { source: "supi-core" });
+    }
+  }
+
+  return ctx.ui.custom<T | null>((tui, theme, _kb, done) => {
+    const widget = new ProgressWidget(tui, theme, title);
+    let finished = false;
+
+    const finish = (result: T | null) => {
+      if (finished) return;
+      finished = true;
+      pi.events.emit("supi:working:end", { source: "supi-core" });
+      widget.dispose();
+      done(result);
+    };
+
+    widget.onAbort = () => {
+      // Widget handles abort signal; runner resolves with cancel/error.
+    };
+
+    pi.events.emit("supi:working:start", { source: "supi-core" });
+    runner(widget.signal, (progress) => widget.updateProgress(progress))
+      .then((result) => finish(result))
+      .catch(() => finish(null));
+
+    return widget;
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-insights",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "SuPi Insights extension — generate usage reports analyzing your PI sessions",
   "license": "MIT",
   "repository": {
@@ -24,14 +24,15 @@
   ],
   "dependencies": {
     "diff": "^9.0.0",
-    "@mrclrchtr/supi-core": "1.10.0"
+    "@mrclrchtr/supi-core": "1.11.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"
   ],
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-ai": "*"
+    "@earendil-works/pi-ai": "*",
+    "typebox": "*"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
@@ -39,6 +40,9 @@
     },
     "@earendil-works/pi-ai": {
       "optional": true
+    },
+    "typebox": {
+      "optional": true
     }
   },
   "pi": {

package/src/extractor.ts

@@ -2,8 +2,26 @@
 
 import { complete } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { callWithJsonResponse } from "@mrclrchtr/supi-core/llm";
+import { Type } from "typebox";
 import type { SessionFacets } from "./types.ts";
-import { withRetry } from "./utils.ts";
+
+// ── TypeBox schema for facet extraction response ──────────────────────────
+
+const FacetSchema = Type.Object({
+  underlyingGoal: Type.String(),
+  goalCategories: Type.Record(Type.String(), Type.Number()),
+  outcome: Type.String(),
+  userSatisfactionCounts: Type.Record(Type.String(), Type.Number()),
+  claudeHelpfulness: Type.String(),
+  sessionType: Type.String(),
+  frictionCounts: Type.Record(Type.String(), Type.Number()),
+  frictionDetail: Type.String(),
+  primarySuccess: Type.String(),
+  briefSummary: Type.String(),
+});
+
+// ── Prompts ───────────────────────────────────────────────────────────────
 
 const FACET_EXTRACTION_PROMPT = `Analyze this PI coding agent session and extract structured facets.
 
@@ -30,6 +48,20 @@ CRITICAL GUIDELINES:
 
 4. If very short or just warmup, use warmup_minimal for goal_category
 
+RESPOND WITH ONLY A VALID JSON OBJECT matching this schema:
+{
+  "underlyingGoal": "What the user fundamentally wanted to achieve",
+  "goalCategories": {"category_name": count, ...},
+  "outcome": "fully_achieved|mostly_achieved|partially_achieved|not_achieved|unclear_from_transcript",
+  "userSatisfactionCounts": {"level": count, ...},
+  "claudeHelpfulness": "unhelpful|slightly_helpful|moderately_helpful|very_helpful|essential",
+  "sessionType": "single_task|multi_task|iterative_refinement|exploration|quick_question",
+  "frictionCounts": {"friction_type": count, ...},
+  "frictionDetail": "One sentence describing friction or empty",
+  "primarySuccess": "none|fast_accurate_search|correct_code_edits|good_explanations|proactive_help|multi_file_changes|good_debugging",
+  "briefSummary": "One sentence: what user wanted and whether they got it"
+}
+
 SESSION:
 `;
 
@@ -44,86 +76,34 @@ Keep it concise - 3-5 sentences. Preserve specific details like file names, erro
 TRANSCRIPT CHUNK:
 `;
 
+// ── Public API ─────────────────────────────────────────────────────────────
+
 export async function extractFacets(
   transcript: string,
   sessionId: string,
   ctx: ExtensionContext,
 ): Promise<SessionFacets | null> {
-  // Resolve model: prefer active model, fall back to any available configured model
-  const model = ctx.model ?? ctx.modelRegistry.getAvailable()[0];
-  if (!model) return null;
-
-  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
-  if (!auth.ok || !auth.apiKey) return null;
-
   // For long transcripts, summarize in chunks first
   const processedTranscript =
     transcript.length > 30000 ? await summarizeTranscript(transcript, ctx) : transcript;
 
-  const jsonPrompt = `${FACET_EXTRACTION_PROMPT}${processedTranscript}
-
-RESPOND WITH ONLY A VALID JSON OBJECT matching this schema:
-{
-  "underlyingGoal": "What the user fundamentally wanted to achieve",
-  "goalCategories": {"category_name": count, ...},
-  "outcome": "fully_achieved|mostly_achieved|partially_achieved|not_achieved|unclear_from_transcript",
-  "userSatisfactionCounts": {"level": count, ...},
-  "claudeHelpfulness": "unhelpful|slightly_helpful|moderately_helpful|very_helpful|essential",
-  "sessionType": "single_task|multi_task|iterative_refinement|exploration|quick_question",
-  "frictionCounts": {"friction_type": count, ...},
-  "frictionDetail": "One sentence describing friction or empty",
-  "primarySuccess": "none|fast_accurate_search|correct_code_edits|good_explanations|proactive_help|multi_file_changes|good_debugging",
-  "briefSummary": "One sentence: what user wanted and whether they got it"
-}`;
-
-  // Attempt the LLM call with up to 2 retries
-  const response = await withRetry(
-    async () => {
-      const res = await complete(
-        model,
-        {
-          systemPrompt: "",
-          messages: [
-            {
-              role: "user",
-              content: [{ type: "text", text: jsonPrompt }],
-              timestamp: Date.now(),
-            },
-          ],
-        },
-        {
-          apiKey: auth.apiKey,
-          headers: auth.headers,
-          signal: ctx.signal,
-          maxTokens: 4096,
-        },
-      );
-      return res;
+  const result = await callWithJsonResponse(
+    ctx,
+    {
+      prompt: `${FACET_EXTRACTION_PROMPT}${processedTranscript}`,
+      maxTokens: 4096,
+      retries: 2,
     },
-    2,
-    1000,
+    FacetSchema,
   );
 
-  if (!response) return null;
-
-  try {
-    const text = response.content
-      .filter((c): c is { type: "text"; text: string } => c.type === "text")
-      .map((c) => c.text)
-      .join("");
-
-    const jsonMatch = text.match(/\{[\s\S]*\}/);
-    if (!jsonMatch) return null;
-
-    const parsed = JSON.parse(jsonMatch[0]) as unknown;
-    if (!isValidSessionFacets(parsed)) return null;
+  if (!result) return null;
 
-    return { ...parsed, sessionId };
-  } catch {
-    return null;
-  }
+  return { ...result.parsed, sessionId } as unknown as SessionFacets;
 }
 
+// ── Transcript chunking ───────────────────────────────────────────────────
+
 async function summarizeTranscript(transcript: string, ctx: ExtensionContext): Promise<string> {
   const model = ctx.model ?? ctx.modelRegistry.getAvailable()[0];
   if (!model) return transcript.slice(0, 30000);
@@ -171,19 +151,3 @@ async function summarizeTranscript(transcript: string, ctx: ExtensionContext): P
 
   return summaries.join("\n\n---\n\n");
 }
-
-function isValidSessionFacets(obj: unknown): obj is Omit<SessionFacets, "sessionId"> {
-  if (!obj || typeof obj !== "object") return false;
-  const o = obj as Record<string, unknown>;
-  return (
-    typeof o.underlyingGoal === "string" &&
-    typeof o.outcome === "string" &&
-    typeof o.briefSummary === "string" &&
-    o.goalCategories !== null &&
-    typeof o.goalCategories === "object" &&
-    o.userSatisfactionCounts !== null &&
-    typeof o.userSatisfactionCounts === "object" &&
-    o.frictionCounts !== null &&
-    typeof o.frictionCounts === "object"
-  );
-}

package/src/generator.ts

@@ -1,13 +1,105 @@
 // Insight generator — produce narrative insights from aggregated data via LLM calls.
 
-import { complete } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { callWithJsonResponse } from "@mrclrchtr/supi-core/llm";
+import { Type } from "typebox";
 import type { AggregatedData, InsightResults, SessionFacets } from "./types.ts";
-import { withRetry } from "./utils.ts";
+
+// ── TypeBox schemas for each insight section ───────────────────────────────
+
+const ProjectAreasSchema = Type.Object({
+  areas: Type.Array(
+    Type.Object({
+      name: Type.String(),
+      sessionCount: Type.Number(),
+      description: Type.String(),
+    }),
+  ),
+});
+
+const InteractionStyleSchema = Type.Object({
+  narrative: Type.String(),
+  keyPattern: Type.String(),
+});
+
+const WhatWorksSchema = Type.Object({
+  intro: Type.String(),
+  impressiveWorkflows: Type.Array(
+    Type.Object({
+      title: Type.String(),
+      description: Type.String(),
+    }),
+  ),
+});
+
+const FrictionAnalysisSchema = Type.Object({
+  intro: Type.String(),
+  categories: Type.Array(
+    Type.Object({
+      category: Type.String(),
+      description: Type.String(),
+      examples: Type.Array(Type.String()),
+    }),
+  ),
+});
+
+const SuggestionsSchema = Type.Object({
+  claudeMdAdditions: Type.Array(
+    Type.Object({
+      addition: Type.String(),
+      why: Type.String(),
+      promptScaffold: Type.String(),
+    }),
+  ),
+  featuresToTry: Type.Array(
+    Type.Object({
+      feature: Type.String(),
+      oneLiner: Type.String(),
+      whyForYou: Type.String(),
+      exampleCode: Type.String(),
+    }),
+  ),
+  usagePatterns: Type.Array(
+    Type.Object({
+      title: Type.String(),
+      suggestion: Type.String(),
+      detail: Type.String(),
+      copyablePrompt: Type.String(),
+    }),
+  ),
+});
+
+const OnTheHorizonSchema = Type.Object({
+  intro: Type.String(),
+  opportunities: Type.Array(
+    Type.Object({
+      title: Type.String(),
+      whatsPossible: Type.String(),
+      howToTry: Type.String(),
+      copyablePrompt: Type.String(),
+    }),
+  ),
+});
+
+const FunEndingSchema = Type.Object({
+  headline: Type.String(),
+  detail: Type.String(),
+});
+
+const AtAGlanceSchema = Type.Object({
+  whatsWorking: Type.String(),
+  whatsHindering: Type.String(),
+  quickWins: Type.String(),
+  ambitiousWorkflows: Type.String(),
+});
+
+// ── Section definitions ──────────────────────────────────────────────────
 
 type InsightSection = {
   name: keyof InsightResults;
   prompt: string;
+  // biome-ignore lint/suspicious/noExplicitAny: TypeBox schema union
+  schema: ReturnType<typeof Type.Object<any>>;
   maxTokens: number;
 };
 
@@ -24,6 +116,7 @@ RESPOND WITH ONLY A VALID JSON OBJECT:
 }
 
 Include 4-5 areas.`,
+    schema: ProjectAreasSchema,
     maxTokens: 4096,
   },
   {
@@ -35,6 +128,7 @@ RESPOND WITH ONLY A VALID JSON OBJECT:
   "narrative": "2-3 paragraphs analyzing HOW the user interacts with PI. Use second person 'you'. Describe patterns: iterate quickly vs detailed upfront specs? Interrupt often or let the agent run? Include specific examples. Use **bold** for key insights.",
   "keyPattern": "One sentence summary of most distinctive interaction style"
 }`,
+    schema: InteractionStyleSchema,
     maxTokens: 4096,
   },
   {
@@ -50,6 +144,7 @@ RESPOND WITH ONLY A VALID JSON OBJECT:
 }
 
 Include 3 impressive workflows.`,
+    schema: WhatWorksSchema,
     maxTokens: 4096,
   },
   {
@@ -65,6 +160,7 @@ RESPOND WITH ONLY A VALID JSON OBJECT:
 }
 
 Include 3 friction categories with 2 examples each.`,
+    schema: FrictionAnalysisSchema,
     maxTokens: 4096,
   },
   {
@@ -85,6 +181,7 @@ RESPOND WITH ONLY A VALID JSON OBJECT:
 }
 
 IMPORTANT: PRIORITIZE instructions that appear MULTIPLE TIMES in the user data.`,
+    schema: SuggestionsSchema,
     maxTokens: 4096,
   },
   {
@@ -100,6 +197,7 @@ RESPOND WITH ONLY A VALID JSON OBJECT:
 }
 
 Include 3 opportunities. Think BIG - autonomous workflows, parallel agents, iterating against tests.`,
+    schema: OnTheHorizonSchema,
     maxTokens: 4096,
   },
   {
@@ -113,10 +211,13 @@ RESPOND WITH ONLY A VALID JSON OBJECT:
 }
 
 Find something genuinely interesting or amusing from the session summaries.`,
+    schema: FunEndingSchema,
     maxTokens: 2048,
   },
 ];
 
+// ── Public API ─────────────────────────────────────────────────────────────
+
 export async function generateInsights(
   data: AggregatedData,
   facets: Map<string, SessionFacets>,
@@ -145,70 +246,25 @@ export async function generateInsights(
   return insights;
 }
 
-async function resolveModel(ctx: ExtensionContext): Promise<{
-  model: NonNullable<ExtensionContext["model"]>;
-  apiKey: string;
-  headers: Record<string, string>;
-} | null> {
-  const model = ctx.model ?? ctx.modelRegistry.getAvailable()[0] ?? null;
-  if (!model) return null;
-  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
-  if (!auth.ok || !auth.apiKey) return null;
-  return { model, apiKey: auth.apiKey, headers: auth.headers ?? {} };
-}
+// ── Section generators ────────────────────────────────────────────────────
 
 async function generateSectionInsight(
   section: InsightSection,
   dataContext: string,
   ctx: ExtensionContext,
 ): Promise<{ name: keyof InsightResults; result: unknown }> {
-  const resolved = await resolveModel(ctx);
-  if (!resolved) return { name: section.name, result: null };
-
-  const { model, apiKey, headers } = resolved;
-
-  const response = await withRetry(
-    async () => {
-      const res = await complete(
-        model,
-        {
-          systemPrompt: "",
-          messages: [
-            {
-              role: "user",
-              content: [{ type: "text", text: `${section.prompt}\n\nDATA:\n${dataContext}` }],
-              timestamp: Date.now(),
-            },
-          ],
-        },
-        {
-          apiKey,
-          headers,
-          signal: ctx.signal,
-          maxTokens: section.maxTokens,
-        },
-      );
-      return res;
+  const result = await callWithJsonResponse(
+    ctx,
+    {
+      prompt: section.prompt,
+      dataContext,
+      maxTokens: section.maxTokens,
+      retries: 2,
     },
-    2,
-    1000,
+    section.schema,
   );
 
-  if (!response) return { name: section.name, result: null };
-
-  const text = response.content
-    .filter((c): c is { type: "text"; text: string } => c.type === "text")
-    .map((c) => c.text)
-    .join("");
-
-  const jsonMatch = text.match(/\{[\s\S]*\}/);
-  if (!jsonMatch) return { name: section.name, result: null };
-
-  try {
-    return { name: section.name, result: JSON.parse(jsonMatch[0]) };
-  } catch {
-    return { name: section.name, result: null };
-  }
+  return { name: section.name, result: result?.parsed ?? null };
 }
 
 async function generateAtAGlance(
@@ -302,55 +358,21 @@ ${featuresText}
 ## On the Horizon
 ${horizonText}`;
 
-  const resolved = await resolveModel(ctx);
-  if (!resolved) return null;
-
-  const { model, apiKey, headers } = resolved;
-
-  const response = await withRetry(
-    async () => {
-      const res = await complete(
-        model,
-        {
-          systemPrompt: "",
-          messages: [
-            {
-              role: "user",
-              content: [{ type: "text", text: prompt }],
-              timestamp: Date.now(),
-            },
-          ],
-        },
-        {
-          apiKey,
-          headers,
-          signal: ctx.signal,
-          maxTokens: 4096,
-        },
-      );
-      return res;
+  const result = await callWithJsonResponse(
+    ctx,
+    {
+      prompt,
+      maxTokens: 4096,
+      retries: 2,
     },
-    2,
-    1000,
+    AtAGlanceSchema,
   );
 
-  if (!response) return null;
-
-  const text = response.content
-    .filter((c): c is { type: "text"; text: string } => c.type === "text")
-    .map((c) => c.text)
-    .join("");
-
-  const jsonMatch = text.match(/\{[\s\S]*\}/);
-  if (!jsonMatch) return null;
-
-  try {
-    return JSON.parse(jsonMatch[0]);
-  } catch {
-    return null;
-  }
+  return result?.parsed ?? null;
 }
 
+// ── Data context ──────────────────────────────────────────────────────────
+
 function buildDataContext(data: AggregatedData, facets: Map<string, SessionFacets>): string {
   const facetSummaries = Array.from(facets.values())
     .slice(0, 50)

package/src/insights.ts

@@ -91,26 +91,23 @@ export default function insightsExtension(pi: ExtensionAPI) {
         label: "Enable insights",
         currentValue: settings.enabled ? "on" : "off",
         values: ["on", "off"],
+        configType: "boolean" as const,
       },
       {
         id: "maxSessions",
         label: "Max sessions to analyze",
         currentValue: String(settings.maxSessions),
         values: ["50", "100", "200", "500"],
+        configType: "number" as const,
       },
       {
         id: "maxFacets",
         label: "Max facet extractions",
         currentValue: String(settings.maxFacets),
         values: ["20", "50", "100"],
+        configType: "number" as const,
       },
     ],
-    // biome-ignore lint/complexity/useMaxParams: registerConfigSettings defines this callback shape.
-    persistChange: (_scope, _cwd, settingId, value, helpers) => {
-      const numSettings = new Set(["maxSessions", "maxFacets"]);
-      const finalValue = numSettings.has(settingId) ? Number(value) : value === "on";
-      helpers.set(settingId, finalValue);
-    },
   });
 
   // ── /supi-insights command ──────────────────────────────────
@@ -128,7 +125,9 @@ export default function insightsExtension(pi: ExtensionAPI) {
       ctx.ui.setWorkingMessage("Analyzing sessions...");
 
       try {
+        pi.events.emit("supi:working:start", { source: "supi-insights" });
         const report = await generateReport(ctx, config);
+        pi.events.emit("supi:working:end", { source: "supi-insights" });
         ctx.ui.setWorkingMessage();
 
         if (!report) {
@@ -183,6 +182,7 @@ export default function insightsExtension(pi: ExtensionAPI) {
 
         ctx.ui.notify(`Insights report saved: ${htmlPath}`, "info");
       } catch (err) {
+        pi.events.emit("supi:working:end", { source: "supi-insights" });
         ctx.ui.setWorkingMessage();
         const message = err instanceof Error ? err.message : String(err);
         ctx.ui.notify(`Insights generation failed: ${message}`, "error");

package/src/utils.ts

@@ -2,29 +2,6 @@
 
 import { extname } from "node:path";
 
-// ── Retry helper for LLM calls ────────────────────────────
-
-/**
- * Attempt an async operation with retries and exponential backoff.
- * Returns the result on success, or null if all attempts fail.
- */
-export async function withRetry<T>(
-  fn: () => Promise<T>,
-  retries = 2,
-  baseDelayMs = 1000,
-): Promise<T | null> {
-  for (let attempt = 0; attempt <= retries; attempt++) {
-    try {
-      return await fn();
-    } catch (_err) {
-      if (attempt < retries) {
-        await new Promise((r) => setTimeout(r, baseDelayMs * 2 ** attempt));
-      }
-    }
-  }
-  return null;
-}
-
 const EXTENSION_TO_LANGUAGE: Record<string, string> = {
   ".ts": "TypeScript",
   ".tsx": "TypeScript",