@mrclrchtr/supi-context 1.3.0 → 1.4.0

package/src/analysis.ts

@@ -1,4 +1,5 @@
 // biome-ignore lint/nursery/noExcessiveLinesPerFile: analysis file is inherently large
+import { dirname, resolve } from "node:path";
 import {
   type BuildSystemPromptOptions,
   buildSessionContext,
@@ -10,6 +11,7 @@ import {
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import { getRegisteredContextProviders } from "@mrclrchtr/supi-core/api";
+
 import { deriveOptionsFromSystemPrompt, extractGuidelinesSection } from "./prompt-inference.ts";
 
 type AgentMessage = Parameters<typeof estimateTokens>[0];
@@ -26,12 +28,15 @@ export interface CategoryTokens {
 export interface ContextFileInfo {
   path: string;
   tokens: number;
+  lines: number;
+  origin: "global" | "project";
 }
 
 export interface InjectedFileInfo {
   file: string;
   turn: number;
   tokens: number;
+  lines: number;
 }
 
 export interface SkillInfo {
@@ -39,6 +44,25 @@ export interface SkillInfo {
   tokens: number;
 }
 
+export interface ToolInfo {
+  name: string;
+  description: string;
+  tokens: number;
+}
+
+/** Per-tool breakdown of the one-line tool snippet shown in "Available tools". */
+export interface ToolSnippetInfo {
+  name: string;
+  tokens: number;
+}
+
+/** Source-attributed guideline info. */
+export interface GuidelineSourceInfo {
+  source: string; // "default" | tool name | "other"
+  tokens: number;
+  bulletCount: number;
+}
+
 export interface ContextProviderSection {
   id: string;
   label: string;
@@ -51,22 +75,29 @@ export interface ContextAnalysis {
   totalTokens: number | null;
   scaled: boolean;
   approximationNote: string | null;
+  full: boolean;
   categories: CategoryTokens & {
     autocompactBuffer: number;
     freeSpace: number;
   };
   systemPromptBreakdown: {
     base: number;
+    instructionFiles: ContextFileInfo[];
     contextFiles: ContextFileInfo[];
     skills: SkillInfo[];
     guidelines: number;
     toolSnippets: number;
+    toolSnippetDetails: ToolSnippetInfo[];
+    guidelineSources: GuidelineSourceInfo[];
     appendText: number;
   };
   injectedFiles: InjectedFileInfo[];
   skills: SkillInfo[];
   guidelines: number;
-  toolDefinitions: { count: number; tokens: number };
+  guidelineBullets: string[];
+  guidelineSources: GuidelineSourceInfo[];
+  toolSnippetDetails: ToolSnippetInfo[];
+  toolDefinitions: { count: number; tokens: number; tools: ToolInfo[] };
   compaction: { summarizedTurns: number } | null;
   providerSections: ContextProviderSection[];
 }
@@ -239,16 +270,50 @@ function collectProviderData(): ContextProviderSection[] {
   return sections;
 }
 
+const INSTRUCTION_FILE_PATTERN = /^(AGENTS|CLAUDE|\.claude\.local)\.md$/i;
+
+function isInstructionFile(path: string): boolean {
+  const basename = path.replace(/\\/g, "/").split("/").pop() ?? "";
+  return INSTRUCTION_FILE_PATTERN.test(basename);
+}
+
+function determineOrigin(filePath: string, cwd: string): "global" | "project" {
+  const resolvedPath = resolve(cwd, filePath);
+  const fileDir = dirname(resolvedPath);
+  let current = cwd;
+  const root = resolve("/");
+  while (true) {
+    if (fileDir === current) return "project";
+    if (current === root) break;
+    const parent = resolve(current, "..");
+    if (parent === current) break;
+    current = parent;
+  }
+  return "global";
+}
+
 function computeContextFiles(
   promptOptions: BuildSystemPromptOptions | undefined,
-): ContextFileInfo[] {
-  const files: ContextFileInfo[] = [];
+  cwd: string,
+): { contextFiles: ContextFileInfo[]; instructionFiles: ContextFileInfo[] } {
+  const contextFiles: ContextFileInfo[] = [];
+  const instructionFiles: ContextFileInfo[] = [];
   if (promptOptions?.contextFiles) {
     for (const cf of promptOptions.contextFiles) {
-      files.push({ path: cf.path, tokens: estimateTextTokens(cf.content) });
+      const info: ContextFileInfo = {
+        path: cf.path,
+        tokens: estimateTextTokens(cf.content),
+        lines: cf.content.split("\n").length,
+        origin: determineOrigin(cf.path, cwd),
+      };
+      if (isInstructionFile(cf.path)) {
+        instructionFiles.push(info);
+      } else {
+        contextFiles.push(info);
+      }
     }
   }
-  return files;
+  return { contextFiles, instructionFiles };
 }
 
 function computeSkills(promptOptions: BuildSystemPromptOptions | undefined): SkillInfo[] {
@@ -262,12 +327,118 @@ function computeSkills(promptOptions: BuildSystemPromptOptions | undefined): Ski
   return skills;
 }
 
+function extractGuidelineBullets(guidelinesText: string | null): string[] {
+  if (!guidelinesText) return [];
+  return guidelinesText
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith("- "))
+    .map((line) => line.slice(2).trim());
+}
+
+/**
+ * Known texts of PI built-in default guidelines.
+ * These are generated by buildSystemPrompt() in the system prompt builder.
+ */
+const DEFAULT_GUIDELINE_TEXTS = new Set([
+  "Use bash for file operations like ls, rg, find",
+  "Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)",
+  "Be concise in your responses",
+  "Show file paths clearly when working with files",
+]);
+
+/**
+ * Known promptGuidelines from PI's built-in tools.
+ * These are hardcoded in the tool definition modules (read, write, edit).
+ */
+const BUILTIN_TOOL_GUIDELINES: Record<string, string[]> = {
+  read: ["Use read to examine files instead of cat or sed."],
+  write: ["Use write only for new files or complete rewrites."],
+  edit: [
+    "Use edit for precise changes (edits[].oldText must match exactly)",
+    "When changing multiple separate locations in one file, use one edit call with multiple entries in edits[] instead of multiple edit calls",
+    "Each edits[].oldText is matched against the original file, not after earlier edits are applied. Do not emit overlapping or nested edits. Merge nearby changes into one edit.",
+    "Keep edits[].oldText as small as possible while still being unique in the file. Do not pad with large unchanged regions.",
+  ],
+};
+
+/**
+ * Build a reverse map from guideline text → tool name so we can look up
+ * which built-in tool (if any) contributed each guideline bullet.
+ */
+function buildGuidelineToToolMap(): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const [tool, guidelines] of Object.entries(BUILTIN_TOOL_GUIDELINES)) {
+    for (const guideline of guidelines) {
+      map.set(guideline, tool);
+    }
+  }
+  return map;
+}
+
+const GUIDELINE_TO_TOOL = buildGuidelineToToolMap();
+
+/**
+ * Given guideline bullets extracted from the system prompt, classify each bullet
+ * by source and compute per-source token counts.
+ */
+function classifyGuidelines(bullets: string[], _activeToolNames: string[]): GuidelineSourceInfo[] {
+  const sources = new Map<string, { chars: number; count: number }>();
+
+  for (const bullet of bullets) {
+    let source: string;
+    if (DEFAULT_GUIDELINE_TEXTS.has(bullet)) {
+      source = "default";
+    } else {
+      const toolName = GUIDELINE_TO_TOOL.get(bullet);
+      source = toolName ?? "other";
+    }
+
+    const entry = sources.get(source) ?? { chars: 0, count: 0 };
+    entry.chars += bullet.length;
+    entry.count += 1;
+    sources.set(source, entry);
+  }
+
+  return Array.from(sources.entries())
+    .map(([source, { chars, count }]) => ({
+      source,
+      tokens: Math.ceil(chars / 4),
+      bulletCount: count,
+    }))
+    .sort((a, b) => {
+      // Default first, then tool sources (alphabetical), then "other" last
+      if (a.source === "default") return -1;
+      if (b.source === "default") return 1;
+      if (a.source === "other") return 1;
+      if (b.source === "other") return -1;
+      return a.source.localeCompare(b.source);
+    });
+}
+
+/**
+ * Build per-tool snippet breakdown from the toolSnippets record.
+ */
+function buildToolSnippetDetails(
+  toolSnippets: Record<string, string> | undefined,
+): ToolSnippetInfo[] {
+  if (!toolSnippets) return [];
+
+  return Object.entries(toolSnippets)
+    .map(([name, snippet]) => ({
+      name,
+      tokens: estimateTextTokens(snippet),
+    }))
+    .sort((a, b) => b.tokens - a.tokens);
+}
+
 function computeSystemPromptBreakdown(
   promptOptions: BuildSystemPromptOptions | undefined,
   systemPromptText: string,
   systemPromptTokens: number,
+  cwd: string,
 ): ContextAnalysis["systemPromptBreakdown"] {
-  const contextFiles = computeContextFiles(promptOptions);
+  const { contextFiles, instructionFiles } = computeContextFiles(promptOptions, cwd);
   const skills = computeSkills(promptOptions);
 
   const skillsTotal = skills.reduce((s, c) => s + c.tokens, 0);
@@ -277,9 +448,13 @@ function computeSystemPromptBreakdown(
     : promptOptions?.promptGuidelines
       ? estimateTextTokens(promptOptions.promptGuidelines.join("\n"))
       : 0;
-  const toolSnippets = promptOptions?.toolSnippets
+  const toolSnippetsTotal = promptOptions?.toolSnippets
     ? estimateTextTokens(Object.values(promptOptions.toolSnippets).join("\n"))
     : 0;
+  const toolSnippetDetails = buildToolSnippetDetails(promptOptions?.toolSnippets);
+  const guidelineBullets = extractGuidelineBullets(inferredGuidelines);
+  const activeToolNames = promptOptions?.selectedTools ?? [];
+  const guidelineSources = classifyGuidelines(guidelineBullets, activeToolNames);
   const appendText = promptOptions?.appendSystemPrompt
     ? estimateTextTokens(promptOptions.appendSystemPrompt)
     : 0;
@@ -289,31 +464,47 @@ function computeSystemPromptBreakdown(
 
   const knownSubtotal =
     contextFiles.reduce((s, c) => s + c.tokens, 0) +
+    instructionFiles.reduce((s, c) => s + c.tokens, 0) +
     skillsTotal +
     guidelines +
-    toolSnippets +
+    toolSnippetsTotal +
     appendText +
     customTokens;
 
   const base = Math.max(0, systemPromptTokens - knownSubtotal);
 
-  return { base, contextFiles, skills, guidelines, toolSnippets, appendText };
+  return {
+    base,
+    instructionFiles,
+    contextFiles,
+    skills,
+    guidelines,
+    toolSnippets: toolSnippetsTotal,
+    toolSnippetDetails,
+    guidelineSources,
+    appendText,
+  };
 }
 
-function computeToolDefinitions(pi: ExtensionAPI): { count: number; tokens: number } {
+function computeToolDefinitions(pi: ExtensionAPI): {
+  count: number;
+  tokens: number;
+  tools: ToolInfo[];
+} {
   const activeToolNames = new Set(pi.getActiveTools());
   const allTools = pi.getAllTools();
   const activeTools = allTools.filter((t) => activeToolNames.has(t.name));
+  const tools = activeTools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    tokens: estimateTextTokens(
+      JSON.stringify({ name: t.name, description: t.description, parameters: t.parameters }),
+    ),
+  }));
   return {
     count: activeTools.length,
-    tokens: activeTools.reduce(
-      (sum, t) =>
-        sum +
-        estimateTextTokens(
-          JSON.stringify({ name: t.name, description: t.description, parameters: t.parameters }),
-        ),
-      0,
-    ),
+    tokens: tools.reduce((sum, t) => sum + t.tokens, 0),
+    tools,
   };
 }
 
@@ -353,7 +544,12 @@ export function extractInjectedContextFiles(messages: AgentMessage[]): InjectedF
       const innerContent = match[3];
       const key = `${file}::${turn}`;
       if (!seen.has(key)) {
-        seen.set(key, { file, turn, tokens: estimateTextTokens(innerContent) });
+        seen.set(key, {
+          file,
+          turn,
+          tokens: estimateTextTokens(innerContent),
+          lines: innerContent.split("\n").length,
+        });
       }
       match = regex.exec(content);
     }
@@ -366,6 +562,7 @@ export function analyzeContext(
   ctx: ExtensionCommandContext,
   pi: ExtensionAPI,
   cachedOptions: BuildSystemPromptOptions | undefined,
+  full = false,
 ): ContextAnalysis {
   const branch = ctx.sessionManager.getBranch();
   const apiView = buildSessionContext(branch);
@@ -403,17 +600,21 @@ export function analyzeContext(
     promptOptions,
     systemPromptText,
     scaling.categories.systemPrompt,
+    ctx.cwd,
   );
   const injectedFiles = extractInjectedContextFiles(apiView.messages);
   const toolDefinitions = computeToolDefinitions(pi);
   const compaction = detectCompaction(branch);
 
+  const guidelineBullets = extractGuidelineBullets(extractGuidelinesSection(systemPromptText));
+
   return {
     modelName: ctx.model?.name ?? ctx.model?.id ?? "No model selected",
     contextWindow,
     totalTokens: scaling.totalTokens,
     scaled: scaling.scaled,
     approximationNote: scaling.approximationNote,
+    full,
     categories: {
       ...scaling.categories,
       autocompactBuffer,
@@ -423,6 +624,9 @@ export function analyzeContext(
     injectedFiles,
     skills: breakdown.skills,
     guidelines: breakdown.guidelines,
+    guidelineBullets,
+    guidelineSources: breakdown.guidelineSources,
+    toolSnippetDetails: breakdown.toolSnippetDetails,
     toolDefinitions,
     compaction,
     providerSections: collectProviderData(),

package/src/context.ts

@@ -15,9 +15,10 @@ export default function contextExtension(pi: ExtensionAPI) {
   });
 
   pi.registerCommand("supi-context", {
-    description: "Show detailed context usage",
-    handler: async (_args, ctx) => {
-      const analysis = analyzeContext(ctx, pi, cachedOptions);
+    description: "Show detailed context usage. Pass 'full' to show all guideline bullets.",
+    handler: async (args, ctx) => {
+      const full = args.trim() === "full";
+      const analysis = analyzeContext(ctx, pi, cachedOptions, full);
       const shortContent = `${formatTokens(analysis.totalTokens ?? 0)} / ${formatTokens(analysis.contextWindow)} tokens`;
 
       pi.sendMessage({