@mrclrchtr/supi-context 4.10.0 → 6.0.0

package/README.md

@@ -36,7 +36,7 @@ The command appends a durable `supi-context` custom entry and uses a dedicated e
 
 ### Agent: Context Pressure Snapshot
 
-`supi_context` is agent-callable when enabled in configuration. It defaults to a one-line, constant-shape JSON **Context Pressure Snapshot**:
+`context_report` is agent-callable when enabled in configuration. It defaults to a one-line, constant-shape JSON **Context Pressure Snapshot**:
 
 ```ts
 interface ContextPressureSnapshot {
@@ -53,7 +53,7 @@ interface ContextPressureSnapshot {
 }
 ```
 
-Use `supi_context({ mode: "full" })` only when diagnostic attribution is needed. Full mode returns compact JSON for the Context Usage Report. If it exceeds Pi's normal tool-output limits, it returns a small valid-JSON envelope with the path to a temporary file containing the complete report.
+Use `context_report({ mode: "full" })` only when diagnostic attribution is needed. Full mode returns compact JSON for the Context Usage Report. If it exceeds Pi's normal tool-output limits, it returns a small valid-JSON envelope with the path to a temporary file containing the complete report.
 
 The tool TUI never shows raw agent JSON: concise results render as a dense snapshot that expands into its metrics; full results expand into the diagnostic report.
 
@@ -71,7 +71,7 @@ The Context Usage Report includes:
 
 The human `/supi-context` command needs no configuration.
 
-To enable the agent-callable `supi_context` tool, set `agentToolEnabled` to `true` in your supi config:
+To enable the agent-callable `context_report` tool, set `agentToolEnabled` to `true` in your supi config:
 
 ```json
 {

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.10.0",
+  "version": "6.0.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {
@@ -53,7 +53,7 @@
     "./api": "./src/api.ts",
     "./config": "./src/config.ts",
     "./context": "./src/context.ts",
-    "./debug": "./src/debug-registry.ts",
+    "./debug": "./src/debug.ts",
     "./evidence-badge": "./src/evidence-badge.ts",
     "./footer-registry": "./src/footer-registry.ts",
     "./llm": "./src/llm.ts",

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

@@ -11,7 +11,7 @@ export * from "./config.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./context.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./debug-registry.ts";
+export * from "./debug.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./evidence-badge.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel

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

@@ -4,9 +4,6 @@
 // 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 {
@@ -25,6 +22,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 +41,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 +54,7 @@ export interface DebugEventQuery {
 export interface DebugEventView {
   id: number;
   timestamp: number;
+  operationId?: string;
   source: string;
   level: DebugLevel;
   category: string;
@@ -84,6 +86,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 +138,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 +206,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 +226,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.ts

@@ -0,0 +1,9 @@
+// Debug domain entry for `@mrclrchtr/supi-core/debug`.
+//
+// Kept separate from debug-registry.ts so debug-timing.ts can import the
+// registry without creating an import cycle through the barrel re-export.
+
+// biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
+export * from "./debug-registry.ts";
+// biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
+export * from "./debug-timing.ts";

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

@@ -11,7 +11,7 @@ export * from "./config.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./context.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./debug-registry.ts";
+export * from "./debug.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./footer-registry.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel

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-context",
-  "version": "4.10.0",
+  "version": "6.0.0",
   "description": "Live context pressure and token-use reports",
   "license": "MIT",
   "repository": {
@@ -32,7 +32,7 @@
   ],
   "dependencies": {
     "typebox": "*",
-    "@mrclrchtr/supi-core": "4.10.0"
+    "@mrclrchtr/supi-core": "6.0.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/config.ts

@@ -2,13 +2,13 @@
 //
 // Config shape (in supi shared config, "context" section):
 // {
-//   "agentToolEnabled": false   // enable the supi_context agent-callable tool
+//   "agentToolEnabled": false   // enable the context_report agent-callable tool
 // }
 
 import { loadSupiConfig } from "@mrclrchtr/supi-core/config";
 
 export interface ContextConfig extends Record<string, unknown> {
-  /** Enable the supi_context agent-callable tool. Default: false */
+  /** Enable the context_report agent-callable tool. Default: false */
   agentToolEnabled: boolean;
 }
 

package/src/context.ts

@@ -1,25 +1,9 @@
-import { StringEnum } from "@earendil-works/pi-ai";
 import type { BuildSystemPromptOptions, ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-import { analyzeContext, analyzeContextPressure } from "./analysis.ts";
+import { analyzeContext } from "./analysis.ts";
 import { loadContextConfig } from "./config.ts";
 import { type ContextReportEntryData, registerContextEntryRenderer } from "./entry-renderer.ts";
 import { registerContextSettings } from "./settings-registration.ts";
-import { promptSnippet, toolDescription } from "./tool/guidance.ts";
-import { serializeFullContextAnalysis } from "./tool/output.ts";
-import {
-  type ContextToolDetails,
-  renderContextToolCall,
-  renderContextToolResult,
-} from "./tool/render.ts";
-
-const contextToolParameters = Type.Object({
-  mode: Type.Optional(
-    StringEnum(["concise", "full"] as const, {
-      description: "Omit for concise capacity data, or use full for the diagnostic report.",
-    }),
-  ),
-});
+import { registerContextReportTool } from "./tool/context_report/register.ts";
 
 export default function contextExtension(pi: ExtensionAPI) {
   let cachedOptions: BuildSystemPromptOptions | undefined;
@@ -48,33 +32,9 @@ export default function contextExtension(pi: ExtensionAPI) {
     });
   });
 
-  // ── supi_context agent tool (gated on config) ────────────
+  // ── context_report agent tool (gated on config) ────────────
 
   if (loadContextConfig(process.cwd()).agentToolEnabled) {
-    pi.registerTool({
-      name: "supi_context",
-      label: "Context Usage",
-      description: toolDescription,
-      promptSnippet,
-      parameters: contextToolParameters,
-      renderCall: renderContextToolCall,
-      renderResult: renderContextToolResult,
-      // biome-ignore lint/complexity/useMaxParams: pi tool execute signature
-      async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-        if (params.mode !== "full") {
-          const snapshot = analyzeContextPressure(ctx);
-          return {
-            content: [{ type: "text", text: JSON.stringify(snapshot) }],
-            details: { mode: "concise", snapshot } satisfies ContextToolDetails,
-          };
-        }
-
-        const analysis = analyzeContext(ctx, pi, cachedOptions);
-        return {
-          content: [{ type: "text", text: await serializeFullContextAnalysis(analysis) }],
-          details: { mode: "full", analysis } satisfies ContextToolDetails,
-        };
-      },
-    });
+    registerContextReportTool(pi, () => cachedOptions);
   }
 }

package/src/settings-registration.ts

@@ -18,7 +18,7 @@ export function registerContextSettings(pi: ExtensionAPI, homeDir?: string): voi
           kind: "boolean" as const,
           key: "agentToolEnabled",
           label: "Agent Tool",
-          description: "Enable supi_context agent tool for context usage queries",
+          description: "Enable context_report agent tool for context usage queries",
         },
       ],
       ...(homeDir ? { homeDir } : {}),

package/src/tool/context_report/execute.ts

@@ -0,0 +1,20 @@
+import type { BuildSystemPromptOptions, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { analyzeContext, analyzeContextPressure } from "../../analysis.ts";
+import { buildConciseResult, buildFullResult } from "./result.ts";
+
+type ContextReportExecute = NonNullable<Parameters<ExtensionAPI["registerTool"]>[0]["execute"]>;
+
+/** Build the context_report execute function. */
+export function makeContextReportExecute(
+  pi: ExtensionAPI,
+  getOptions: () => BuildSystemPromptOptions | undefined,
+): ContextReportExecute {
+  // biome-ignore lint/complexity/useMaxParams: pi tool execute signature
+  return async (_toolCallId, params, _signal, _onUpdate, ctx) => {
+    const mode = (params as { mode?: string }).mode;
+    if (mode !== "full") {
+      return buildConciseResult(analyzeContextPressure(ctx));
+    }
+    return buildFullResult(analyzeContext(ctx, pi, getOptions()));
+  };
+}

package/src/tool/{guidance.ts → context_report/guidance.ts}

@@ -1,10 +1,10 @@
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize } from "@earendil-works/pi-coding-agent";
 
-// Tool description and prompt snippet for the supi_context agent tool.
+// Tool description and prompt snippet for the context_report agent tool.
 
 export const toolDescription =
   "Report current context capacity. Omit mode for a concise, constant-shape pressure snapshot; use mode: full only when diagnostic attribution is needed. Full output is compact JSON and is replaced with a temporary-file envelope above " +
   `${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)}.`;
 
 export const promptSnippet =
-  "supi_context — concise context-pressure snapshot (mode: full for diagnostics)";
+  "context_report — concise context-pressure snapshot (mode: full for diagnostics)";

package/src/tool/context_report/register.ts

@@ -0,0 +1,20 @@
+import type { BuildSystemPromptOptions, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { makeContextReportExecute } from "./execute.ts";
+import { promptSnippet, toolDescription } from "./guidance.ts";
+import { renderContextToolCall, renderContextToolResult } from "./render.ts";
+import { contextReportSpec } from "./spec.ts";
+
+/** Register the context_report agent tool. */
+export function registerContextReportTool(
+  pi: ExtensionAPI,
+  getOptions: () => BuildSystemPromptOptions | undefined,
+): void {
+  pi.registerTool({
+    ...contextReportSpec,
+    description: toolDescription,
+    promptSnippet,
+    execute: makeContextReportExecute(pi, getOptions),
+    renderCall: renderContextToolCall,
+    renderResult: renderContextToolResult,
+  });
+}

package/src/tool/{render.ts → context_report/render.ts}

@@ -1,22 +1,13 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
-import type { ContextAnalysis } from "../analysis.ts";
-import { type ContextPressureSnapshot, createContextPressureSnapshot } from "../capacity.ts";
-import { ContextReportComponent } from "../report-component.ts";
-import { ContextPressureComponent } from "../snapshot-component.ts";
-
-export interface ContextToolConciseDetails {
-  mode: "concise";
-  snapshot: ContextPressureSnapshot;
-}
-
-export interface ContextToolFullDetails {
-  mode: "full";
-  analysis: ContextAnalysis;
-}
-
-/** TUI data mirrors the mode-specific data returned to the agent. */
-export type ContextToolDetails = ContextToolConciseDetails | ContextToolFullDetails;
+import { createContextPressureSnapshot } from "../../capacity.ts";
+import { ContextReportComponent } from "../../report-component.ts";
+import { ContextPressureComponent } from "../../snapshot-component.ts";
+import type {
+  ContextToolConciseDetails,
+  ContextToolDetails,
+  ContextToolFullDetails,
+} from "./result.ts";
 
 interface ContextToolResult {
   content: Array<{ type: string; text?: string }>;
@@ -37,7 +28,7 @@ export function renderContextToolCall(args: unknown, theme: Theme): Text {
     (args as { mode?: string }).mode === "full"
       ? "full"
       : "concise";
-  const content = `${theme.fg("toolTitle", "supi_context")} ${theme.fg("muted", mode)}`;
+  const content = `${theme.fg("toolTitle", "context_report")} ${theme.fg("muted", mode)}`;
   return new Text(content, 0, 0);
 }
 
@@ -51,7 +42,7 @@ export function renderContextToolResult(
   }
 
   if (result?.isError) {
-    return new Text(theme.fg("error", "supi_context failed"), 0, 0);
+    return new Text(theme.fg("error", "context_report failed"), 0, 0);
   }
 
   const details = extractDetails(result?.details);

package/src/tool/{output.ts → context_report/result.ts}

@@ -1,12 +1,27 @@
 import { mkdtemp, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
 import {
   DEFAULT_MAX_BYTES,
   DEFAULT_MAX_LINES,
   truncateHead,
 } from "@earendil-works/pi-coding-agent";
-import type { ContextAnalysis } from "../analysis.ts";
+import type { ContextAnalysis } from "../../analysis.ts";
+import type { ContextPressureSnapshot } from "../../capacity.ts";
+
+export interface ContextToolConciseDetails {
+  mode: "concise";
+  snapshot: ContextPressureSnapshot;
+}
+
+export interface ContextToolFullDetails {
+  mode: "full";
+  analysis: ContextAnalysis;
+}
+
+/** Mode-specific details returned to the agent and mirrored for TUI rendering. */
+export type ContextToolDetails = ContextToolConciseDetails | ContextToolFullDetails;
 
 interface TruncatedOutputEnvelope {
   truncated: true;
@@ -49,3 +64,23 @@ export async function serializeFullContextAnalysis(analysis: ContextAnalysis): P
   };
   return JSON.stringify(envelope);
 }
+
+/** Assemble the concise-mode model-facing result. */
+export function buildConciseResult(
+  snapshot: ContextPressureSnapshot,
+): AgentToolResult<ContextToolConciseDetails> {
+  return {
+    content: [{ type: "text", text: JSON.stringify(snapshot) }],
+    details: { mode: "concise", snapshot },
+  };
+}
+
+/** Assemble the full-mode model-facing result. */
+export async function buildFullResult(
+  analysis: ContextAnalysis,
+): Promise<AgentToolResult<ContextToolFullDetails>> {
+  return {
+    content: [{ type: "text", text: await serializeFullContextAnalysis(analysis) }],
+    details: { mode: "full", analysis },
+  };
+}

package/src/tool/context_report/spec.ts

@@ -0,0 +1,18 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+
+export const CONTEXT_REPORT_TOOL_NAME = "context_report";
+export const CONTEXT_REPORT_TOOL_LABEL = "Context Usage";
+
+/** Canonical provider-facing metadata for the context_report tool. */
+export const contextReportSpec = {
+  name: CONTEXT_REPORT_TOOL_NAME,
+  label: CONTEXT_REPORT_TOOL_LABEL,
+  parameters: Type.Object({
+    mode: Type.Optional(
+      StringEnum(["concise", "full"] as const, {
+        description: "Omit for concise capacity data, or use full for the diagnostic report.",
+      }),
+    ),
+  }),
+} as const;