@mrclrchtr/supi-context 5.0.0 → 6.0.1

package/README.md

@@ -6,6 +6,8 @@
 
 # @mrclrchtr/supi-context — Context Window and Token Usage Monitor for Pi
 
+[![GitHub stars](https://img.shields.io/github/stars/mrclrchtr/supi)](https://github.com/mrclrchtr/supi/stargazers) [![npm downloads](https://img.shields.io/npm/dm/@mrclrchtr/supi-context)](https://www.npmjs.com/package/@mrclrchtr/supi-context)
+
 Adds context window and token usage monitoring to the [Pi coding agent](https://github.com/earendil-works/pi).
 
 ## Install
@@ -36,7 +38,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 +55,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 +73,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

@@ -6,6 +6,8 @@
 
 # @mrclrchtr/supi-core
 
+[![GitHub stars](https://img.shields.io/github/stars/mrclrchtr/supi)](https://github.com/mrclrchtr/supi/stargazers)
+
 Shared infrastructure for SuPi extensions.
 
 This is a **pure library** — it does not register any pi commands or tools. The `/supi-settings` command is now available through `@mrclrchtr/supi-settings`.

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "5.0.0",
+  "version": "6.0.1",
   "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/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 {

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-context",
-  "version": "5.0.0",
+  "version": "6.0.1",
   "description": "Live context pressure and token-use reports",
   "license": "MIT",
   "repository": {
@@ -32,7 +32,7 @@
   ],
   "dependencies": {
     "typebox": "*",
-    "@mrclrchtr/supi-core": "5.0.0"
+    "@mrclrchtr/supi-core": "6.0.1"
   },
   "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;