@mrclrchtr/supi-context 2.6.1 → 2.8.0

package/src/format-summary.ts

@@ -15,13 +15,27 @@ import {
 } from "./format-helpers.ts";
 import { formatTokens } from "./utils.ts";
 
+function formatPercentage(value: number | null): string {
+  return value === null ? "?" : `${value.toFixed(1)}%`;
+}
+
 export function renderSummary(analysis: ContextAnalysis, theme: Theme, width: number): string[] {
-  const used = analysis.totalTokens ?? 0;
   const health = theme.fg(healthColor(analysis), "●");
   const usage =
-    analysis.contextWindow > 0
-      ? `${formatTokens(used)} / ${formatTokens(analysis.contextWindow)} tokens (${pct(used, analysis.contextWindow)})`
-      : `${formatTokens(used)} tokens`;
+    analysis.contextWindow !== null
+      ? `${formatTokens(analysis.usedTokens)} / ${formatTokens(analysis.contextWindow)} tokens (${formatPercentage(analysis.usagePercent)} usage)`
+      : `${formatTokens(analysis.usedTokens)} tokens`;
+  const capacityParts: string[] = [];
+
+  if (analysis.headroomTokens !== null) {
+    capacityParts.push(`Headroom ${formatTokens(analysis.headroomTokens)}`);
+  }
+  if (analysis.compactionEnabled) {
+    capacityParts.push(`Compaction reserve ${formatTokens(analysis.reserveTokens)}`);
+  }
+  if (analysis.pressurePercent !== null) {
+    capacityParts.push(`Pressure ${formatPercentage(analysis.pressurePercent)}`);
+  }
 
   const lines = [
     truncateToWidth(
@@ -30,6 +44,9 @@ export function renderSummary(analysis: ContextAnalysis, theme: Theme, width: nu
     ),
   ];
 
+  if (capacityParts.length > 0) {
+    lines.push(...wrapReportText(theme.fg("dim", capacityParts.join("  ·  ")), width));
+  }
   if (analysis.approximationNote) {
     lines.push(...wrapReportText(theme.fg("warning", analysis.approximationNote), width));
   }
@@ -38,16 +55,16 @@ export function renderSummary(analysis: ContextAnalysis, theme: Theme, width: nu
 }
 
 export function renderUsageBar(analysis: ContextAnalysis, theme: Theme, width: number): string[] {
-  if (analysis.contextWindow <= 0) {
+  if (analysis.contextWindow === null) {
     return [theme.fg("dim", "No model selected — usage bar unavailable")];
   }
 
-  const percentLabel = pct(analysis.totalTokens ?? 0, analysis.contextWindow);
+  const percentLabel = formatPercentage(analysis.usagePercent);
   const barWidth = Math.max(12, Math.min(48, width - visibleWidth(percentLabel) - 3));
   const values = [
     ...CATEGORY_ORDER.map((key) => analysis.categories[key]),
-    analysis.categories.autocompactBuffer,
-    analysis.categories.freeSpace,
+    analysis.reserveTokens,
+    analysis.headroomTokens ?? 0,
   ];
   const counts = allocateBlocks(values, barWidth);
 
@@ -85,11 +102,11 @@ export function renderUsageBar(analysis: ContextAnalysis, theme: Theme, width: n
     if (analysis.categories[key] <= 0) continue;
     legendParts.push(`${theme.fg(CATEGORY_COLORS[key], "●")} ${CATEGORY_LABELS[key]}`);
   }
-  if (analysis.categories.autocompactBuffer > 0) {
-    legendParts.push(`${theme.fg("warning", "▒")} Autocompact buffer`);
+  if (analysis.reserveTokens > 0) {
+    legendParts.push(`${theme.fg("warning", "▒")} Compaction reserve`);
   }
-  if (analysis.categories.freeSpace > 0) {
-    legendParts.push(`${theme.fg("dim", "░")} Free space`);
+  if (analysis.headroomTokens !== null && analysis.headroomTokens > 0) {
+    legendParts.push(`${theme.fg("dim", "░")} Headroom`);
   }
 
   return [barLine, ...wrapReportText(legendParts.join(theme.fg("dim", "  •  ")), width)];
@@ -107,31 +124,20 @@ export function renderCategoryBreakdown(
     label: string;
     color: Parameters<Theme["fg"]>[0];
     tokens: number;
-  }> = [
-    ...CATEGORY_ORDER.map((key) => ({
-      label: CATEGORY_LABELS[key],
-      color: CATEGORY_COLORS[key],
-      tokens: analysis.categories[key],
-    })),
-    {
-      label: "Autocompact buffer",
-      color: "warning",
-      tokens: analysis.categories.autocompactBuffer,
-    },
-    {
-      label: "Free space",
-      color: "dim",
-      tokens: analysis.categories.freeSpace,
-    },
-  ];
+  }> = CATEGORY_ORDER.map((key) => ({
+    label: CATEGORY_LABELS[key],
+    color: CATEGORY_COLORS[key],
+    tokens: analysis.categories[key],
+  }));
 
   const labelWidth = Math.max(18, Math.min(22, width - 22));
+  const total = analysis.contextWindow ?? 0;
   for (const row of rows) {
-    if (row.tokens <= 0 && row.label !== "Free space") continue;
+    if (row.tokens <= 0) continue;
     const bullet = theme.fg(row.color, "●");
     const label = padRight(row.label, labelWidth);
     const tokens = padLeft(formatTokens(row.tokens), 8);
-    const percentage = padLeft(pct(row.tokens, analysis.contextWindow), 7);
+    const percentage = padLeft(pct(row.tokens, total), 7);
     lines.push(truncateToWidth(`  ${bullet} ${label} ${tokens} ${percentage}`, width));
   }
 

package/src/format.ts

@@ -18,10 +18,14 @@ import {
   renderUsageBar,
 } from "./format-summary.ts";
 
+/** Presentation mode for a Context Usage Report. */
+export type ContextReportMode = "preview" | "full";
+
 export function formatContextReport(
   analysis: ContextAnalysis,
   theme: Theme,
   width = 200,
+  mode: ContextReportMode = "preview",
 ): string[] {
   const safeWidth = clampReportWidth(width);
   const lines: string[] = [];
@@ -41,8 +45,8 @@ export function formatContextReport(
     renderContextFilesSection(analysis, theme, safeWidth),
     renderInjectedFilesSection(analysis, theme, safeWidth),
     renderSkillsSection(analysis, theme, safeWidth),
-    renderGuidelinesSection(analysis, theme, safeWidth),
-    renderToolDefinitionsSection(analysis, theme, safeWidth),
+    renderGuidelinesSection(analysis, theme, safeWidth, mode === "full"),
+    renderToolDefinitionsSection(analysis, theme, safeWidth, mode === "full"),
     renderCompactionNote(analysis, theme, safeWidth),
     renderProviderSections(analysis, theme, safeWidth),
   ].filter((section) => section.length > 0);

package/src/report-component.ts

@@ -1,8 +1,8 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import type { ContextAnalysis } from "./analysis.ts";
-import { formatContextReport } from "./format.ts";
+import { type ContextReportMode, formatContextReport } from "./format.ts";
 
-/** Width-aware rendered context report shared by message and tool renderers. */
+/** Width-aware Context Usage Report shared by custom-entry and tool renderers. */
 export class ContextReportComponent {
   private cachedWidth?: number;
   private cachedLines?: string[];
@@ -10,6 +10,7 @@ export class ContextReportComponent {
   constructor(
     private readonly analysis: ContextAnalysis,
     private readonly theme: Theme,
+    private readonly mode: ContextReportMode = "preview",
   ) {}
 
   render(width: number): string[] {
@@ -17,7 +18,7 @@ export class ContextReportComponent {
       return this.cachedLines;
     }
 
-    const lines = formatContextReport(this.analysis, this.theme, width);
+    const lines = formatContextReport(this.analysis, this.theme, width, this.mode);
     this.cachedWidth = width;
     this.cachedLines = lines;
     return lines;

package/src/snapshot-component.ts

@@ -0,0 +1,75 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, truncateToWidth } from "@earendil-works/pi-tui";
+import type { ContextPressureSnapshot } from "./capacity.ts";
+import { healthColor } from "./format-helpers.ts";
+import { formatTokens } from "./utils.ts";
+
+function formatPercentage(value: number | null): string {
+  return value === null ? "unavailable" : `${value.toFixed(1)}%`;
+}
+
+function formatTokenValue(value: number | null): string {
+  return value === null ? "unavailable" : formatTokens(value);
+}
+
+/**
+ * Width-safe TUI renderer for the small Context Pressure Snapshot.
+ *
+ * The collapsed view is intentionally one dense line. Expansion exposes every
+ * snapshot field without falling back to the raw JSON returned to the agent.
+ */
+export class ContextPressureComponent implements Component {
+  constructor(
+    private readonly snapshot: ContextPressureSnapshot,
+    private readonly theme: Theme,
+    private readonly expanded: boolean,
+  ) {}
+
+  render(width: number): string[] {
+    return this.expanded ? this.renderExpanded(width) : [this.renderCollapsed(width)];
+  }
+
+  invalidate(): void {}
+
+  private renderCollapsed(width: number): string {
+    const usage =
+      this.snapshot.contextWindow === null
+        ? `${formatTokens(this.snapshot.usedTokens)} used`
+        : `${formatTokens(this.snapshot.usedTokens)}/${formatTokens(this.snapshot.contextWindow)} used`;
+    const parts = [
+      `${this.theme.fg(healthColor(this.snapshot), "●")} ${this.theme.fg("text", usage)}`,
+      `${this.theme.fg("dim", "headroom")} ${this.theme.fg("muted", formatTokenValue(this.snapshot.headroomTokens))}`,
+      `${this.theme.fg("dim", "pressure")} ${this.theme.fg("muted", formatPercentage(this.snapshot.pressurePercent))}`,
+      this.theme.fg("muted", this.snapshot.modelName),
+    ];
+
+    return truncateToWidth(parts.join(` ${this.theme.fg("dim", "·")} `), width);
+  }
+
+  private renderExpanded(width: number): string[] {
+    const values: Array<[string, string]> = [
+      ["Model", this.snapshot.modelName],
+      ["Context window", formatTokenValue(this.snapshot.contextWindow)],
+      ["Used", formatTokens(this.snapshot.usedTokens)],
+      ["Usage", formatPercentage(this.snapshot.usagePercent)],
+      ["Auto-compaction", this.snapshot.compactionEnabled ? "enabled" : "disabled"],
+      ["Compaction reserve", formatTokens(this.snapshot.reserveTokens)],
+      ["Headroom", formatTokenValue(this.snapshot.headroomTokens)],
+      ["Pressure", formatPercentage(this.snapshot.pressurePercent)],
+      ["Compacted", this.snapshot.compacted ? "yes" : "no"],
+    ];
+    const labelWidth = Math.max(8, Math.min(18, width - 12));
+    const lines = values.map(([label, value]) =>
+      truncateToWidth(
+        `${this.theme.fg("dim", `${label.padEnd(labelWidth)} `)}${this.theme.fg("text", value)}`,
+        width,
+      ),
+    );
+
+    if (this.snapshot.approximationNote) {
+      lines.push(truncateToWidth(this.theme.fg("warning", this.snapshot.approximationNote), width));
+    }
+
+    return lines;
+  }
+}

package/src/tool/guidance.ts

@@ -1,10 +1,13 @@
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize } from "@earendil-works/pi-coding-agent";
+
 // Prompt guidance and tool description for the supi_context agent tool.
 
 export const toolDescription =
-  "Report current PI context usage: token breakdown, context window, compaction, injected files, guideline sources, tool definitions, and provider sections.";
+  "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 — context usage report (token breakdown, context window)";
+  "supi_context — concise context-pressure snapshot (mode: full for diagnostics)";
 
 export const promptGuidelines = [
   "Use supi_context before large operations or when context usage is near the limit.",

package/src/tool/output.ts

@@ -0,0 +1,51 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  truncateHead,
+} from "@earendil-works/pi-coding-agent";
+import type { ContextAnalysis } from "../analysis.ts";
+
+interface TruncatedOutputEnvelope {
+  truncated: true;
+  fullOutputPath: string;
+  totalLines: number;
+  totalBytes: number;
+  maxLines: number;
+  maxBytes: number;
+}
+
+/**
+ * Serialize a diagnostic report without ever returning invalid partial JSON.
+ *
+ * When Pi's normal tool-output limits would truncate the report, the complete
+ * compact JSON is stored in a temporary file and the agent receives a small,
+ * valid JSON envelope pointing to it instead.
+ */
+export async function serializeFullContextAnalysis(analysis: ContextAnalysis): Promise<string> {
+  const fullJson = JSON.stringify(analysis);
+  const truncation = truncateHead(fullJson, {
+    maxLines: DEFAULT_MAX_LINES,
+    maxBytes: DEFAULT_MAX_BYTES,
+  });
+
+  if (!truncation.truncated) {
+    return fullJson;
+  }
+
+  const outputDir = await mkdtemp(join(tmpdir(), "supi-context-"));
+  const fullOutputPath = join(outputDir, "context-usage-report.json");
+  await writeFile(fullOutputPath, fullJson, "utf8");
+
+  const envelope: TruncatedOutputEnvelope = {
+    truncated: true,
+    fullOutputPath,
+    totalLines: truncation.totalLines,
+    totalBytes: truncation.totalBytes,
+    maxLines: DEFAULT_MAX_LINES,
+    maxBytes: DEFAULT_MAX_BYTES,
+  };
+  return JSON.stringify(envelope);
+}

package/src/tool/render.ts

@@ -1,14 +1,23 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import type { ContextAnalysis } from "../analysis.ts";
-import { healthColor, pct } from "../format-helpers.ts";
+import { type ContextPressureSnapshot, createContextPressureSnapshot } from "../capacity.ts";
 import { ContextReportComponent } from "../report-component.ts";
-import { formatTokens, pluralize } from "../utils.ts";
+import { ContextPressureComponent } from "../snapshot-component.ts";
 
-export interface ContextToolDetails {
+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;
+
 interface ContextToolResult {
   content: Array<{ type: string; text?: string }>;
   details?: unknown;
@@ -20,8 +29,15 @@ interface ResultOptions {
   isPartial: boolean;
 }
 
-export function renderContextToolCall(_args: unknown, theme: Theme): Text {
-  const content = `${theme.fg("toolTitle", "supi_context")} ${theme.fg("muted", "current session")}`;
+export function renderContextToolCall(args: unknown, theme: Theme): Text {
+  const mode =
+    args &&
+    typeof args === "object" &&
+    "mode" in args &&
+    (args as { mode?: string }).mode === "full"
+      ? "full"
+      : "concise";
+  const content = `${theme.fg("toolTitle", "supi_context")} ${theme.fg("muted", mode)}`;
   return new Text(content, 0, 0);
 }
 
@@ -29,7 +45,7 @@ export function renderContextToolResult(
   result: ContextToolResult | undefined,
   options: ResultOptions,
   theme: Theme,
-): Text | ContextReportComponent {
+): Text | ContextPressureComponent | ContextReportComponent {
   if (options.isPartial) {
     return new Text(theme.fg("warning", "Analyzing context…"), 0, 0);
   }
@@ -38,53 +54,37 @@ export function renderContextToolResult(
     return new Text(theme.fg("error", "supi_context failed"), 0, 0);
   }
 
-  const analysis = extractAnalysis(result?.details);
-  if (!analysis) {
+  const details = extractDetails(result?.details);
+  if (!details) {
     return new Text(theme.fg("dim", "No context analysis data"), 0, 0);
   }
 
+  if (details.mode === "concise") {
+    return new ContextPressureComponent(details.snapshot, theme, options.expanded);
+  }
+
   if (options.expanded) {
-    return new ContextReportComponent(analysis, theme);
+    return new ContextReportComponent(details.analysis, theme, "full");
   }
 
-  return new Text(formatCollapsedSummary(analysis, theme), 0, 0);
+  return new ContextPressureComponent(
+    createContextPressureSnapshot(details.analysis.modelName, details.analysis),
+    theme,
+    false,
+  );
 }
 
-function extractAnalysis(details: unknown): ContextAnalysis | undefined {
-  if (!details || typeof details !== "object" || !("analysis" in details)) {
+function extractDetails(details: unknown): ContextToolDetails | undefined {
+  if (!details || typeof details !== "object" || !("mode" in details)) {
     return undefined;
   }
-  return (details as ContextToolDetails).analysis;
-}
-
-function formatCollapsedSummary(analysis: ContextAnalysis, theme: Theme): string {
-  const used = analysis.totalTokens ?? 0;
-  const usage =
-    analysis.contextWindow > 0
-      ? `${formatTokens(used)} / ${formatTokens(analysis.contextWindow)} (${pct(used, analysis.contextWindow)})`
-      : `${formatTokens(used)} tokens`;
-  const dot = theme.fg("dim", "·");
-  const parts = [
-    `${theme.fg(healthColor(analysis), "●")} ${theme.fg("dim", "usage")} ${theme.fg("text", theme.bold(usage))}`,
-  ];
-
-  if (analysis.contextWindow > 0) {
-    parts.push(
-      `${theme.fg("dim", "free")} ${theme.fg("muted", formatTokens(analysis.categories.freeSpace))}`,
-    );
-  }
 
-  if (analysis.compaction) {
-    parts.push(
-      `${theme.fg("dim", "compacted")} ${theme.fg("muted", pluralize(analysis.compaction.summarizedTurns, "turn", "turns"))}`,
-    );
+  const mode = (details as { mode?: unknown }).mode;
+  if (mode === "concise" && "snapshot" in details) {
+    return details as ContextToolConciseDetails;
   }
-
-  parts.push(`${theme.fg("dim", "model")} ${theme.fg("muted", analysis.modelName)}`);
-
-  if (!analysis.approximationNote) {
-    return parts.join(` ${dot} `);
+  if (mode === "full" && "analysis" in details) {
+    return details as ContextToolFullDetails;
   }
-
-  return `${parts.join(` ${dot} `)}\n${theme.fg("warning", analysis.approximationNote)}`;
+  return undefined;
 }

package/src/renderer.ts

@@ -1,15 +0,0 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
-import type { ContextAnalysis } from "./analysis.ts";
-import { ContextReportComponent } from "./report-component.ts";
-
-export function registerContextRenderer(pi: ExtensionAPI): void {
-  pi.registerMessageRenderer("supi-context", (message, _renderOptions, theme) => {
-    const analysis = (message.details as { analysis?: ContextAnalysis } | undefined)?.analysis;
-    if (!analysis) {
-      return new Text(theme.fg("dim", "No context analysis data"), 1, 0);
-    }
-
-    return new ContextReportComponent(analysis, theme);
-  });
-}