@mrclrchtr/supi-context 1.15.0 → 1.16.1

package/README.md

@@ -26,13 +26,16 @@ pi install ./packages/supi-context
 
 ## What you get
 
-After install, pi gets one user command:
+After install, pi gets one user command and an optional agent-callable tool:
 
 - `/supi-context` — render a detailed context-usage report for the current session
 - `/supi-context full` — render the same report with the full guideline and tool-definition lists instead of previews
+- `supi_context` — agent-callable tool (disabled by default; see Configuration)
 
 The command sends a custom `supi-context` message, and this package registers a dedicated renderer so the report shows up as a structured TUI view instead of plain text.
 
+The `supi_context` tool returns the same analysis as JSON, so the agent can inspect context usage programmatically — useful for checking remaining capacity before large operations or after heavy tool results.
+
 ## What the report shows
 
 The report is meant to answer questions like:
@@ -66,9 +69,21 @@ It includes:
 
 ## Configuration
 
-No settings are required.
+No settings are required for the `/supi-context` command.
+
+To enable the `supi_context` agent tool, set `agentToolEnabled` to `true` in your supi config:
+
+```json
+{
+  "supi-context": {
+    "agentToolEnabled": true
+  }
+}
+```
+
+Or toggle it via `/supi-settings` → **Context** → **Agent Tool**, then `/reload`.
 
-This package does not add a model-callable tool; it adds a user command only.
+The tool is disabled by default and requires a `/reload` or restart after toggling.
 
 ## Notes
 
@@ -79,7 +94,9 @@ This package does not add a model-callable tool; it adds a user command only.
 
 ## Source
 
-- `src/context.ts` — command registration, cached prompt-option handling, and renderer wiring
+- `src/context.ts` — command registration, agent tool registration, cached prompt-option handling, and renderer wiring
+- `src/config.ts` — config loading with `agentToolEnabled` toggle
+- `src/settings-registration.ts` — `/supi-settings` registration for the agent tool toggle
 - `src/analysis.ts` — token accounting, attribution, and report data assembly
 - `src/format.ts` — report orchestration for the TUI view
 - `src/format-helpers.ts` — shared numeric and category helpers for report rendering
@@ -87,6 +104,7 @@ This package does not add a model-callable tool; it adds a user command only.
 - `src/format-sections.ts` — instruction file, context file, skill, guideline, tool, compaction, and provider sections
 - `src/prompt-inference.ts` — fallback recovery of context files, skills, and guideline sections from the live system prompt
 - `src/renderer.ts` — custom renderer for `supi-context` messages
+- `src/tool/guidance.ts` — tool description, prompt snippet, and guidelines for the agent tool
 - `src/utils.ts` — token and plural-format helpers
 
 Tests live under `__tests__/unit/`.

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.15.0",
+  "version": "1.16.1",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-context",
-  "version": "1.15.0",
+  "version": "1.16.1",
   "description": "SuPi Context extension — detailed context usage report via /supi-context command",
   "license": "MIT",
   "repository": {
@@ -30,7 +30,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "1.15.0"
+    "typebox": "*",
+    "@mrclrchtr/supi-core": "1.16.1"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/analysis.ts

@@ -4,7 +4,7 @@ import {
   type BuildSystemPromptOptions,
   buildSessionContext,
   type ExtensionAPI,
-  type ExtensionCommandContext,
+  type ExtensionContext,
   type estimateTokens,
   formatSkillsForPrompt,
   getLatestCompactionEntry,
@@ -508,9 +508,7 @@ function computeToolDefinitions(pi: ExtensionAPI): {
   };
 }
 
-function detectCompaction(
-  branch: ReturnType<ExtensionCommandContext["sessionManager"]["getBranch"]>,
-): {
+function detectCompaction(branch: ReturnType<ExtensionContext["sessionManager"]["getBranch"]>): {
   summarizedTurns: number;
 } | null {
   const compactionEntry = getLatestCompactionEntry(branch);
@@ -559,7 +557,7 @@ export function extractInjectedContextFiles(messages: AgentMessage[]): InjectedF
 }
 
 export function analyzeContext(
-  ctx: ExtensionCommandContext,
+  ctx: ExtensionContext,
   pi: ExtensionAPI,
   cachedOptions: BuildSystemPromptOptions | undefined,
   full = false,

package/src/config.ts

@@ -0,0 +1,22 @@
+// Configuration for supi-context.
+//
+// Config shape (in supi shared config, "context" section):
+// {
+//   "agentToolEnabled": false   // enable the supi_context agent-callable tool
+// }
+
+import { loadSupiConfig } from "@mrclrchtr/supi-core/config";
+
+export interface ContextConfig {
+  /** Enable the supi_context agent-callable tool. Default: false */
+  agentToolEnabled: boolean;
+}
+
+export const CONTEXT_DEFAULTS: ContextConfig = {
+  agentToolEnabled: false,
+};
+
+/** Load merged supi-context config for the given working directory. */
+export function loadContextConfig(cwd: string, homeDir?: string): ContextConfig {
+  return loadSupiConfig("context", cwd, CONTEXT_DEFAULTS, { homeDir });
+}

package/src/context.ts

@@ -1,11 +1,18 @@
 import type { BuildSystemPromptOptions, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
 import { analyzeContext } from "./analysis.ts";
+import { loadContextConfig } from "./config.ts";
 import { registerContextRenderer } from "./renderer.ts";
+import { registerContextSettings } from "./settings-registration.ts";
+import { promptGuidelines, promptSnippet, toolDescription } from "./tool/guidance.ts";
 import { formatTokens } from "./utils.ts";
 
 export default function contextExtension(pi: ExtensionAPI) {
   let cachedOptions: BuildSystemPromptOptions | undefined;
 
+  // Register settings synchronously during factory
+  registerContextSettings();
+
   pi.on("before_agent_start", async (event) => {
     cachedOptions = event.systemPromptOptions;
   });
@@ -31,4 +38,25 @@ export default function contextExtension(pi: ExtensionAPI) {
   });
 
   registerContextRenderer(pi);
+
+  // ── supi_context agent tool (gated on config) ────────────
+
+  if (loadContextConfig(process.cwd()).agentToolEnabled) {
+    pi.registerTool({
+      name: "supi_context",
+      label: "Context Usage",
+      description: toolDescription,
+      promptSnippet,
+      parameters: Type.Object({}),
+      promptGuidelines,
+      // biome-ignore lint/complexity/useMaxParams: pi tool execute signature
+      async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+        const analysis = analyzeContext(ctx, pi, cachedOptions, true);
+        return {
+          content: [{ type: "text", text: JSON.stringify(analysis, null, 2) }],
+          details: undefined,
+        };
+      },
+    });
+  }
 }

package/src/prompt-inference.ts

@@ -1,6 +1,6 @@
 import type {
   BuildSystemPromptOptions,
-  ExtensionCommandContext,
+  ExtensionContext,
   Skill,
 } from "@earendil-works/pi-coding-agent";
 
@@ -123,7 +123,7 @@ export function extractGuidelinesSection(systemPrompt: string): string | null {
 }
 
 export function deriveOptionsFromSystemPrompt(
-  ctx: ExtensionCommandContext,
+  ctx: ExtensionContext,
   cachedOptions: BuildSystemPromptOptions | undefined,
 ): BuildSystemPromptOptions | undefined {
   const systemPrompt = ctx.getSystemPrompt();

package/src/settings-registration.ts

@@ -0,0 +1,25 @@
+// supi-context settings registration for the supi settings registry.
+
+import { registerConfigSettings } from "@mrclrchtr/supi-core/config";
+import { CONTEXT_DEFAULTS } from "./config.ts";
+
+/** Register supi-context settings with the supi settings registry. */
+export function registerContextSettings(homeDir?: string): void {
+  registerConfigSettings({
+    id: "context",
+    label: "Context",
+    section: "context",
+    defaults: CONTEXT_DEFAULTS,
+    buildItems: (settings) => [
+      {
+        id: "agentToolEnabled",
+        label: "Agent Tool",
+        description: "Enable supi_context agent tool for context usage queries",
+        currentValue: settings.agentToolEnabled ? "on" : "off",
+        values: ["on", "off"],
+        configType: "boolean" as const,
+      },
+    ],
+    ...(homeDir ? { homeDir } : {}),
+  });
+}

package/src/tool/guidance.ts

@@ -0,0 +1,13 @@
+// Prompt guidance and tool description for the supi_context agent tool.
+
+export const toolDescription =
+  "Get detailed context usage information for the current session — token breakdown, context window, compaction state, injected files, guideline sources, and more.";
+
+export const promptSnippet =
+  "supi_context — context usage report (token breakdown, context window)";
+
+export const promptGuidelines = [
+  "Use supi_context to check context window usage when approaching limits or after large tool results.",
+  "Use supi_context before large operations to gauge remaining context window capacity.",
+  "Prefer supi_context over asking the user to run /supi-context — it gives you the same data directly.",
+];