@mrclrchtr/supi-debug 4.9.0 → 5.0.0

package/README.md

@@ -30,7 +30,7 @@ After install, this package wires the shared debug registry into three user-faci
 - `supi_debug` — let the model query recent debug events during troubleshooting
 - `/supi-settings` integration — configure whether events are captured and how much data is exposed
 
-It also registers a **Debug** provider section for `/supi-context`.
+It also registers a **Debug** provider section for `/supi-context`, and ships a `/supi-tooling-retro` prompt template for post-task retrospective feedback on the SuPi tooling used in the completed task.
 
 ## Event behavior
 
@@ -40,6 +40,12 @@ It also registers a **Debug** provider section for `/supi-context`.
 - if debug capture is disabled, no events are retained
 - agent-facing access is blocked, sanitized, or raw depending on settings
 
+### Identity disclosure
+
+Retained and persisted LSP debug events may identify local workspaces and files. Since the LSP telemetry expansion, LSP events can carry the absolute workspace root (`cwd`), the configured server name (`server`), workspace-relative file paths (`file`), exact LSP method names (`method`), and the server root (`root`). Identity strings are bounded to 512 UTF-16 code units and server lists to 16 entries.
+
+Identity fields are **not** secret-redacted. The debug registry redacts secret keys and secret-looking values (tokens, passwords, API keys, authorization headers, URL credentials), but server names, file paths, method names, and workspace roots pass through unredacted by design, so local protocol failures stay diagnosable. Treat retained and persisted LSP events as potentially identifying your local machine, project layout, and file names.
+
 ## Rendering
 
 `/supi-debug` uses a custom TUI message renderer that shows two levels of detail:
@@ -63,6 +69,7 @@ Rendered fields per event:
 - optional `cwd`
 - optional `data`
 - optional `rawData`
+- optional `operationId` for events directly owned by one public `code_*` call
 
 ### Why collapsed by default
 
@@ -83,11 +90,12 @@ Both `/supi-debug` and `supi_debug` support the same basic filters:
 - `source`
 - `level`
 - `category`
+- exact `operationId`
 - `limit`
 
 For historical sessions, pass `sessionFile` to `supi_debug`, or
 `sessionFile=<path>` to `/supi-debug`. Historical sessions never retain raw data.
-The tool also accepts `includeRaw` for live-session data when settings allow it.
+The tool also accepts `includeRaw` for live-session data when settings allow it. A Debug Operation ID groups direct request ownership only. It is not a security identity, distributed trace, raw Pi Tool-call identity, or time-window correlation.
 
 ## Settings
 

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

@@ -28,6 +28,7 @@ pnpm add @mrclrchtr/supi-core
 - `loadSupiConfig()` — merged config with resolution order `defaults <- global <- project`
 - `loadSupiConfigForScope()` — load one scope at a time for settings UIs
 - `writeSupiConfig()` — persist values
+- `replaceSupiConfigSection()` — replace one nested section while preserving other sections
 - `removeSupiConfigKey()` — remove a key or override
 
 Config file locations:
@@ -49,6 +50,7 @@ Config file locations:
 
 - context-provider registry for `/supi-context`
 - debug-event registry and monotonic phase timers for producers that want shared debug capture
+- optional Debug Operation IDs for exact, directly owned public Tool-call correlation; ambient events stay uncorrelated
 - settings registry used by `/supi-settings`
 
 ### Project and session helpers

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "4.9.0",
+  "version": "5.0.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {

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

@@ -148,6 +148,37 @@ export function writeSupiConfig(
   fs.writeFileSync(configPath, `${JSON.stringify(existing, null, 2)}\n`, "utf-8");
 }
 
+/**
+ * Replace one complete config section while preserving other sections.
+ *
+ * This is useful for nested settings that must remove stale keys as part of
+ * one update. An empty section is removed from the config file.
+ */
+export function replaceSupiConfigSection(
+  loc: SupiConfigLocation,
+  value: Record<string, unknown>,
+  options?: SupiConfigOptions,
+): void {
+  const configPath = getSupiConfigPath(loc.scope, loc.cwd, options);
+  const existing = readJsonFile(configPath) ?? {};
+
+  if (Object.keys(value).length > 0) existing[loc.section] = value;
+  else delete existing[loc.section];
+
+  const content = Object.keys(existing).length > 0 ? `${JSON.stringify(existing, null, 2)}\n` : "";
+  if (content) {
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, content, "utf-8");
+    return;
+  }
+
+  try {
+    fs.unlinkSync(configPath);
+  } catch {
+    // File may not exist.
+  }
+}
+
 /**
  * Remove a key from a config section.
  * Used by `interval default` to remove the project override.

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

@@ -1,10 +1,12 @@
 // supi-core config domain — config loading.
 export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
+  getSupiConfigPath,
   loadSupiConfig,
   loadSupiConfigForScope,
   loadSupiConfigSectionForScope,
   readJsonFile,
   removeSupiConfigKey,
+  replaceSupiConfigSection,
   writeSupiConfig,
 } from "./config/config.ts";

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

@@ -25,6 +25,8 @@ export const DEBUG_REGISTRY_DEFAULTS: DebugRegistryConfig = {
 };
 
 export interface DebugEventInput {
+  /** Opaque identity for events directly owned by one public Tool call. */
+  operationId?: string;
   source: string;
   level: DebugLevel;
   category: string;
@@ -42,6 +44,8 @@ export interface DebugEvent extends DebugEventInput {
 }
 
 export interface DebugEventQuery {
+  /** Match one exact Debug Operation ID. */
+  operationId?: string;
   source?: string;
   level?: DebugLevel;
   category?: string;
@@ -53,6 +57,7 @@ export interface DebugEventQuery {
 export interface DebugEventView {
   id: number;
   timestamp: number;
+  operationId?: string;
   source: string;
   level: DebugLevel;
   category: string;
@@ -84,6 +89,7 @@ interface DebugRegistryState {
 }
 
 const REGISTRY_KEY = Symbol.for("@mrclrchtr/supi-core/debug-registry");
+const DEBUG_OPERATION_ID_RE = /^op-[A-Za-z0-9_-]{21}[AQgw]$/;
 const SECRET_KEY_RE = /(?:token|password|passwd|secret|api[_-]?key|authorization|credential)/i;
 const ENV_SECRET_RE =
   /\b([A-Za-z0-9_]*(?:token|password|passwd|secret|api[_-]?key|authorization|credential)[A-Za-z0-9_]*)=(?:'[^']*'|"[^"]*"|\S+)/gi;
@@ -135,11 +141,17 @@ export function isDebugLevel(value: unknown): value is DebugLevel {
   return value === "debug" || value === "info" || value === "warning" || value === "error";
 }
 
-/** Match a debug event against the supported source, level, and category filters. */
+/** Return whether a value has the exact 16-byte base64url Debug Operation ID form. */
+export function isDebugOperationId(value: unknown): value is string {
+  return typeof value === "string" && DEBUG_OPERATION_ID_RE.test(value);
+}
+
+/** Match a debug event against the supported exact filters. */
 export function matchesDebugEventQuery(
-  event: Pick<DebugEventView, "source" | "level" | "category">,
-  query: Pick<DebugEventQuery, "source" | "level" | "category">,
+  event: Pick<DebugEventView, "operationId" | "source" | "level" | "category">,
+  query: Pick<DebugEventQuery, "operationId" | "source" | "level" | "category">,
 ): boolean {
+  if (query.operationId && event.operationId !== query.operationId) return false;
   if (query.source && event.source !== query.source) return false;
   if (query.level && event.level !== query.level) return false;
   if (query.category && event.category !== query.category) return false;
@@ -197,6 +209,7 @@ function toSanitizedView(event: DebugEvent): DebugEventView {
   return {
     id: event.id,
     timestamp: event.timestamp,
+    operationId: event.operationId,
     source: event.source,
     level: event.level,
     category: event.category,
@@ -216,6 +229,9 @@ export function subscribeDebugEvents(listener: DebugEventListener): () => void {
 /** Record a session-local debug event if debugging is enabled. */
 export function recordDebugEvent(input: DebugEventInput): DebugEvent | null {
   const state = getState();
+  if (input.operationId !== undefined && !isDebugOperationId(input.operationId)) {
+    return null;
+  }
   if (!state.config.enabled) {
     return null;
   }

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

@@ -46,13 +46,21 @@ export interface DebugTimer {
  * 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.
+ * Clock, event-construction, and registry failures are isolated from the
+ * measured operation and make the timer a no-op.
  */
 export function startDebugTimer(options: DebugTimerOptions = {}): DebugTimer {
   if (!isDebugRegistryEnabled()) return DISABLED_DEBUG_TIMER;
   const now = options.now ?? performance.now.bind(performance);
-  const startedAt = now();
+  let startedAt: number;
+  try {
+    startedAt = now();
+  } catch {
+    return DISABLED_DEBUG_TIMER;
+  }
   let previousAt = startedAt;
   let finished = false;
+  let failed = false;
   const phases = new Map<string, number>();
 
   const markAt = (phase: string, current: number): void => {
@@ -65,30 +73,35 @@ export function startDebugTimer(options: DebugTimerOptions = {}): DebugTimer {
   return {
     enabled: true,
     mark(phase) {
-      if (finished) return;
-      markAt(phase, now());
+      if (finished || failed) return;
+      try {
+        markAt(phase, now());
+      } catch {
+        failed = true;
+      }
     },
     finish(input, finalPhase) {
-      if (finished) return null;
-      if (!isDebugRegistryEnabled()) {
-        finished = true;
+      if (finished || failed) return null;
+      finished = true;
+      try {
+        if (!isDebugRegistryEnabled()) return null;
+        const completedAt = now();
+        if (finalPhase) markAt(finalPhase, completedAt);
+        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 },
+        });
+      } catch {
         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 },
-      });
     },
   };
 }

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

@@ -41,7 +41,10 @@ export interface SettingsApplyResult {
  */
 export interface SettingsModule {
   id: string;
+  /** Human-readable section label shown in the UI. */
   label: string;
+  /** Optional label that groups this module within its section. */
+  subsection?: string;
   read(context: SettingsContext): Promise<SettingsSnapshot>;
   apply(request: SettingsActionRequest): Promise<SettingsApplyResult>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-debug",
-  "version": "4.9.0",
+  "version": "5.0.0",
   "description": "Capture and inspect SuPi debug events",
   "license": "MIT",
   "repository": {
@@ -28,10 +28,11 @@
   "type": "module",
   "files": [
     "src/**/*.ts",
+    "prompts",
     "README.md"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "4.9.0"
+    "@mrclrchtr/supi-core": "5.0.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/prompts/supi-tooling-retro.md

@@ -0,0 +1,62 @@
+---
+description: Retrospect on SuPi tooling used during the completed task
+---
+
+Produce a compact, evidence-based retrospective of the task that just ended. Evaluate SuPi-provided tools, skills, prompts, extensions, and injected context—not the entire suite in the abstract.
+
+## Evidence rules
+
+- Reconstruct the retrospective from this session only. Do not invent tool calls, outcomes, failures, token costs, or user impact.
+- Tag claims as `[observed]`, `[inferred]`, or `[unknown]`. An observed claim is supported by the transcript or a tool result; an inferred claim is plausible but untested.
+- Use the exact surface name shown in the session. Do not treat a tool being available but unused as evidence that it failed.
+- If no SuPi surface was used or relevant, say so explicitly. Do not manufacture a wishlist; list only task-specific, plausible missed help.
+- Do not make tool calls or perform follow-up investigation. Stop after writing the retrospective.
+
+## Evaluate
+
+- Actual SuPi surfaces used: what they enabled, where they fell short, and any failure or friction.
+- Missed opportunities: a relevant unused tool (like supi-code-intelligence tools) or context source, and why it was missed—discoverability, guidance, timing, capability, or not applicable.
+- Missing pieces: a concrete utility, capability, documentation page, example, or output improvement that would have changed this task.
+- Noise: redundant instructions, repeated advice without added value, stale or irrelevant context, excessive output, unnecessary long paths, poor timing, or misleading guidance. Do not criticize necessary context without naming the avoidable cost.
+- Keep SuPi/tooling recommendations separate from general code or project recommendations.
+
+## Output rules
+
+- Keep the result under about 500 words and specific to this task.
+- Prefer concrete evidence and observed friction over generic praise or a general feature wishlist.
+- If a section has no supported item, write `None identified` and explain the evidence limit briefly.
+- Include at most three recommendations. Each must name a changeable surface (tool, prompt, skill, docs, guidance, or feature), the proposed change, and the expected benefit. Do not recommend “use the tool more” unless discoverability is the identified cause.
+- Do not edit files, open issues, update OpenSpec artifacts, or take any other follow-up action.
+
+## Required output
+
+## SuPi Tooling Retrospective
+
+**Task completed**: <1–2 sentence summary>
+
+### Tools used
+- `[observed]` **`<tool, skill, prompt, extension, or context>`** — concrete help, friction, or failure.
+- If none: `None identified — no SuPi surface materially participated in this task.`
+
+### Missed opportunities
+- `[inferred]` **`<surface>`** — task-specific help it might have provided; cause: discoverability, guidance, timing, capability, or not applicable.
+- If none: `None identified — do not infer a gap from non-use alone.`
+
+### Missing pieces
+- `[observed|inferred]` **`<utility, feature, docs, example, or output change>`** — the concrete gap and how it affected this task.
+- If none: `None identified.`
+
+### Unhelpful or noisy context
+- `[observed]` **`<instruction, context, or output>`** — what was unnecessary or costly and how it could be reduced or better timed.
+- If none: `None identified.`
+
+### Prioritized recommendations
+1. **`<named surface>`** — <specific change>; <expected benefit>; confidence: <high|medium|low>.
+2. **`<named surface>`** — <specific change>; <expected benefit>; confidence: <high|medium|low>.
+3. **`<named surface>`** — <specific change>; <expected benefit>; confidence: <high|medium|low>.
+- Include only supported recommendations; if none are supported, write `None identified`.
+
+### Confidence / evidence
+- Direct evidence: <what the session demonstrates>
+- Inference: <what is plausible but untested>
+- Limits: <what the session cannot establish>

package/src/command.ts

@@ -0,0 +1,132 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { getDebugEvents } from "@mrclrchtr/supi-core/debug";
+import { resolveToolPath } from "@mrclrchtr/supi-core/path";
+import { formatDebugEvents, truncateDebugOutput } from "./output.ts";
+import type { DebugToolParams } from "./query.ts";
+import { parseDebugCommandArgs } from "./query.ts";
+import { createDebugMessageDetails } from "./renderer.ts";
+import { readSessionDebugEvents } from "./session-events.ts";
+
+const DEBUG_REPORT_TYPE = "supi-debug-report";
+
+interface DebugConfig {
+  enabled: boolean;
+}
+
+interface DebugCommandDependencies {
+  pi: ExtensionAPI;
+  applyConfig: (cwd: string) => DebugConfig;
+  normalizeLimit: (value: string) => number;
+}
+
+function persistedDebugFilters(query: DebugToolParams) {
+  return {
+    operationId: query.operationId,
+    source: query.source,
+    level: query.level,
+    category: query.category,
+    limit: query.limit,
+  };
+}
+
+async function sendPersistedDebugReport(
+  query: DebugToolParams,
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): Promise<void> {
+  const statusKey = "supi-debug";
+  const setStatus = ctx.ui?.setStatus;
+  try {
+    const filters = persistedDebugFilters(query);
+    if (!query.sessionFile)
+      throw new Error("A session file is required for historical debug events.");
+    const sessionFile = resolveToolPath(ctx.cwd, query.sessionFile);
+    const persisted =
+      ctx.signal || setStatus
+        ? await readSessionDebugEvents(sessionFile, filters, {
+            signal: ctx.signal,
+            onProgress: (progress) => {
+              setStatus?.(
+                statusKey,
+                `Reading debug events: ${progress.scannedLines.toLocaleString("en-US")} lines · ${progress.matchedEvents.toLocaleString("en-US")} matches`,
+              );
+            },
+          })
+        : await readSessionDebugEvents(sessionFile, filters);
+    const output = truncateDebugOutput(
+      formatDebugEvents(persisted.events, false, false, persisted.persistedEventCount).join("\n"),
+    );
+    pi.sendMessage({
+      customType: DEBUG_REPORT_TYPE,
+      content: output.text,
+      display: true,
+      details: createDebugMessageDetails(persisted.events, {
+        sessionFile: query.sessionFile,
+        persistedEventCount: persisted.persistedEventCount,
+        eventCount: persisted.events.length,
+        emptyReason:
+          persisted.events.length === 0
+            ? persisted.persistedEventCount === 0
+              ? "no-persisted-events"
+              : "no-matches"
+            : undefined,
+        truncation: output.truncation,
+      }),
+    });
+  } finally {
+    setStatus?.(statusKey, undefined);
+  }
+}
+
+function sendLiveDebugReport(query: DebugToolParams, pi: ExtensionAPI): void {
+  const { events, rawAccessDenied } = getDebugEvents(query);
+  const output = truncateDebugOutput(formatDebugEvents(events, rawAccessDenied).join("\n"));
+  pi.sendMessage({
+    customType: DEBUG_REPORT_TYPE,
+    content: output.text,
+    display: true,
+    details: createDebugMessageDetails(events, {
+      rawAccessDenied,
+      eventCount: events.length,
+      emptyReason: events.length === 0 ? "no-matches" : undefined,
+      truncation: output.truncation,
+    }),
+  });
+}
+
+async function handleDebugCommand(
+  args: string,
+  ctx: ExtensionCommandContext,
+  dependencies: DebugCommandDependencies,
+): Promise<void> {
+  const { pi, applyConfig, normalizeLimit } = dependencies;
+  const config = applyConfig(ctx.cwd);
+  const query = parseDebugCommandArgs(args, normalizeLimit);
+  if (!config.enabled && !query.sessionFile) {
+    pi.sendMessage({
+      customType: DEBUG_REPORT_TYPE,
+      content: "SuPi debug event capture is disabled. Enable Debug in /supi-settings.",
+      display: true,
+    });
+    return;
+  }
+
+  if (query.sessionFile) {
+    await sendPersistedDebugReport(query, ctx, pi);
+    return;
+  }
+  sendLiveDebugReport(query, pi);
+}
+
+/** Register the user-facing debug command. */
+export function registerDebugCommand(
+  pi: ExtensionAPI,
+  applyConfig: (cwd: string) => DebugConfig,
+  normalizeLimit: (value: string) => number,
+): void {
+  const dependencies = { pi, applyConfig, normalizeLimit };
+  pi.registerCommand("supi-debug", {
+    description: "Show recent SuPi debug events",
+    handler: (args, ctx) => handleDebugCommand(args, ctx, dependencies),
+  });
+}