@mrclrchtr/supi-skills 4.8.0 → 4.9.0

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

@@ -48,7 +48,7 @@ Config file locations:
 ### 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
@@ -108,5 +108,7 @@ export default function myExtension(pi: ExtensionAPI) {
 
 - `src/api.ts` — exported library surface
 - `src/config.ts` — shared config loading and writing
+- `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.8.0",
+  "version": "4.9.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-skills",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "Scoped skill controls and skill input shortcuts for PI",
   "license": "MIT",
   "repository": {
@@ -30,7 +30,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "4.8.0"
+    "@mrclrchtr/supi-core": "4.9.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"