@mrclrchtr/supi-context 2.6.1 → 2.7.0

package/README.md

@@ -8,7 +8,7 @@
 
 # @mrclrchtr/supi-context
 
-Adds a `/supi-context` command to the [pi coding agent](https://github.com/earendil-works/pi) so you can inspect how the current session is spending its context window.
+Adds context-capacity observability to the [pi coding agent](https://github.com/earendil-works/pi).
 
 ## Install
 
@@ -22,56 +22,58 @@ For local development:
 pi install ./packages/supi-context
 ```
 
-![Context usage report](https://raw.githubusercontent.com/mrclrchtr/supi/main/screenshots/supi-context.png)
+## Two concepts, two surfaces
 
-## What you get
+- A **Context Pressure Snapshot** is a small point-in-time capacity reading for deciding whether a session has room for another operation.
+- A **Context Usage Report** is a diagnostic account of where the session's context is spent.
 
-After install, pi gets one user command and an optional agent-callable tool:
+### Human: Context Usage Report
 
-- `/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)
+In interactive TUI mode, pi gets these commands:
 
-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.
+- `/supi-context` — render a report with guideline and tool previews
+- `/supi-context full` — render the same report with complete guideline and tool lists
 
-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. In the TUI, the tool renders a compact usage summary by default and expands into the same structured report as `/supi-context`.
+The command appends a durable `supi-context` custom entry and uses a dedicated entry renderer. The report remains in the transcript but never enters LLM context.
+
+### 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**:
+
+```ts
+interface ContextPressureSnapshot {
+  modelName: string;
+  contextWindow: number | null;
+  usedTokens: number;
+  usagePercent: number | null;
+  compactionEnabled: boolean;
+  reserveTokens: number;
+  headroomTokens: number | null;
+  pressurePercent: number | null;
+  compacted: boolean;
+  approximationNote: string | null;
+}
+```
+
+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.
+
+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.
 
 ## What the report shows
 
-The report is meant to answer questions like:
-
-- what is taking up space in the current context window?
-- how much room is left before compaction pressure gets worse?
-- which instruction files, context files, skills, guidelines, or tools are expensive?
-- what extra context was injected by other SuPi extensions?
-
-It includes:
-
-- model name, context-window size, and total token usage
-- approximation or pending-usage notes when exact usage data is not available yet
-- a visual usage bar for system prompt, user messages, assistant messages, tool calls, tool results, other, autocompact buffer, and free space
-- a category breakdown table for the same usage buckets
-- a system-prompt composition breakdown for:
-  - base prompt content
-  - instruction files (`AGENTS.md`, `CLAUDE.md`, etc.)
-  - other context files loaded into the system prompt
-  - active skills
-  - guidelines
-  - tool snippets
-  - append text
-- instruction-file details with token cost, line count, and detected origin (`project` vs `global`)
-- legacy injected subdirectory context files from older `supi-claude-md` sessions, when present
-- active skill names with per-skill token counts
-- guideline bullet previews, plus source attribution for PI defaults, known built-in tools (`read`, `write`, `edit`), and `other`
-- active tool definitions with per-tool definition token counts and snippet-token columns when available
-- a compaction note when older turns were summarized
-- extra provider sections from extensions registered through the shared context-provider registry in `@mrclrchtr/supi-core`
+The Context Usage Report includes:
+
+- model name, context-window size, used tokens, usage percentage, pressure percentage, and **Headroom**
+- the effective **Compaction reserve** and factual presence of compaction on the active branch
+- approximation or pending-usage notes when exact usage is not available
+- a visual usage bar and attribution-category breakdown for system prompt, messages, tool calls, tool results, and other context
+- system-prompt composition, instruction/context files, skills, guideline sources, tool definitions, injected files, and registered provider sections
 
 ## Configuration
 
-No settings are required for the `/supi-context` command.
+The human `/supi-context` command needs no configuration.
 
-To enable the `supi_context` agent tool, set `agentToolEnabled` to `true` in your supi config:
+To enable the agent-callable `supi_context` tool, set `agentToolEnabled` to `true` in your supi config:
 
 ```json
 {
@@ -87,26 +89,18 @@ The tool is disabled by default and requires a `/reload` or restart after toggli
 
 ## Notes
 
-- The command uses the latest cached `systemPromptOptions` captured during `before_agent_start`.
-- If those prompt options are missing or incomplete, the package backfills context files and skills by re-parsing the current system prompt.
-- Exact totals come from pi's current context-usage data when available. Otherwise the report falls back to rough estimates and/or scales estimated category totals to the latest measured total.
-- If no model is selected yet, the report can still render, but the context-window bar cannot show capacity.
+- The extension caches the latest `systemPromptOptions` from `before_agent_start`. If those are missing or incomplete, it backfills context files and skills from the current system prompt.
+- Exact usage comes from Pi's current context-usage data when available. Otherwise the extension estimates usage and preserves an approximation note.
+- The Active Context Limit is the auto-compaction threshold while auto-compaction is enabled, otherwise the raw model context window. Headroom and pressure use that limit.
 
 ## Source
 
-- `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
-- `src/format-summary.ts` — summary, usage bar, category, and composition sections
-- `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/report-component.ts` — shared width-aware report component for message and tool renderers
-- `src/tool/guidance.ts` — tool description, prompt snippet, and guidelines for the agent tool
-- `src/tool/render.ts` — TUI call/result renderer for the agent tool
-- `src/utils.ts` — token and plural-format helpers
+- `src/context.ts` — surface registration and cached prompt-option handling
+- `src/capacity.ts` — shared capacity analysis and snapshot shape
+- `src/analysis.ts` — diagnostic attribution and report data assembly
+- `src/entry-renderer.ts` — TUI-only custom-entry renderer for the human command
+- `src/format*.ts` and `src/report-component.ts` — Context Usage Report rendering
+- `src/snapshot-component.ts` — compact, width-safe snapshot rendering
+- `src/tool/guidance.ts`, `src/tool/output.ts`, and `src/tool/render.ts` — agent-tool guidance, safe full JSON output, and tool rendering
 
 Tests live under `__tests__/unit/`.

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

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mrclrchtr/supi-context",
-  "version": "2.6.1",
-  "description": "SuPi Context extension — detailed context usage report via /supi-context command",
+  "version": "2.7.0",
+  "description": "SuPi Context extension — agent pressure snapshots and TUI usage reports",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -32,16 +32,20 @@
   ],
   "dependencies": {
     "typebox": "*",
-    "@mrclrchtr/supi-core": "2.6.1"
+    "@mrclrchtr/supi-core": "2.7.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"
   ],
   "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*"
   },
   "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
     "@earendil-works/pi-coding-agent": {
       "optional": true
     },
@@ -52,8 +56,7 @@
   "pi": {
     "extensions": [
       "./src/extension.ts"
-    ],
-    "image": "https://raw.githubusercontent.com/mrclrchtr/supi/main/screenshots/supi-context.png"
+    ]
   },
   "main": "src/api.ts",
   "exports": {

package/src/analysis.ts

@@ -5,13 +5,18 @@ import {
   buildSessionContext,
   type ExtensionAPI,
   type ExtensionContext,
-  type estimateTokens,
+  estimateTokens,
   formatSkillsForPrompt,
   getLatestCompactionEntry,
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import { getRegisteredContextProviders } from "@mrclrchtr/supi-core/context";
 
+import {
+  analyzeContextCapacity,
+  type ContextPressureSnapshot,
+  createContextPressureSnapshot,
+} from "./capacity.ts";
 import { deriveOptionsFromSystemPrompt, extractGuidelinesSection } from "./prompt-inference.ts";
 
 type AgentMessage = Parameters<typeof estimateTokens>[0];
@@ -69,17 +74,9 @@ export interface ContextProviderSection {
   data: Record<string, string | number>;
 }
 
-export interface ContextAnalysis {
-  modelName: string;
-  contextWindow: number;
-  totalTokens: number | null;
+export interface ContextAnalysis extends ContextPressureSnapshot {
   scaled: boolean;
-  approximationNote: string | null;
-  full: boolean;
-  categories: CategoryTokens & {
-    autocompactBuffer: number;
-    freeSpace: number;
-  };
+  categories: CategoryTokens;
   systemPromptBreakdown: {
     base: number;
     instructionFiles: ContextFileInfo[];
@@ -98,7 +95,6 @@ export interface ContextAnalysis {
   guidelineSources: GuidelineSourceInfo[];
   toolSnippetDetails: ToolSnippetInfo[];
   toolDefinitions: { count: number; tokens: number; tools: ToolInfo[] };
-  compaction: { summarizedTurns: number } | null;
   providerSections: ContextProviderSection[];
 }
 
@@ -106,39 +102,6 @@ export function estimateTextTokens(text: string): number {
   return Math.ceil(text.length / 4);
 }
 
-function estimateGenericContent(content: unknown): number {
-  if (typeof content === "string") {
-    return estimateTextTokens(content);
-  }
-  if (Array.isArray(content)) {
-    let chars = 0;
-    for (const block of content as Array<{ type?: string; text?: string }>) {
-      if (block.type === "text" && block.text) {
-        chars += block.text.length;
-      }
-    }
-    return Math.ceil(chars / 4);
-  }
-  return 0;
-}
-
-function estimateUserMessage(msg: Extract<AgentMessage, { role: "user" }>): number {
-  const content = msg.content;
-  if (typeof content === "string") {
-    return estimateTextTokens(content);
-  }
-  if (Array.isArray(content)) {
-    let chars = 0;
-    for (const block of content) {
-      if (block.type === "text" && block.text) {
-        chars += block.text.length;
-      }
-    }
-    return Math.ceil(chars / 4);
-  }
-  return 0;
-}
-
 function estimateAssistantMessage(msg: Extract<AgentMessage, { role: "assistant" }>): {
   text: number;
   toolCalls: number;
@@ -169,7 +132,7 @@ function estimateMessageByCategory(msg: AgentMessage): {
 } {
   if (msg.role === "user") {
     return {
-      user: estimateUserMessage(msg),
+      user: estimateTokens(msg),
       assistantText: 0,
       toolCalls: 0,
       toolResult: 0,
@@ -185,7 +148,7 @@ function estimateMessageByCategory(msg: AgentMessage): {
       user: 0,
       assistantText: 0,
       toolCalls: 0,
-      toolResult: estimateGenericContent(msg.content),
+      toolResult: estimateTokens(msg),
       other: 0,
     };
   }
@@ -194,10 +157,14 @@ function estimateMessageByCategory(msg: AgentMessage): {
     assistantText: 0,
     toolCalls: 0,
     toolResult: 0,
-    other: estimateGenericContent((msg as unknown as Record<string, unknown>).content),
+    other: estimateTokens(msg),
   };
 }
 
+function estimateMessageTokens(msg: AgentMessage): number {
+  return estimateTokens(msg);
+}
+
 function computeMessageCategories(messages: AgentMessage[]): CategoryTokens {
   const categories: CategoryTokens = {
     systemPrompt: 0,
@@ -220,6 +187,26 @@ function computeMessageCategories(messages: AgentMessage[]): CategoryTokens {
   return categories;
 }
 
+interface ScalingResult {
+  categories: CategoryTokens;
+  scaled: boolean;
+  approximationNote: string | null;
+  usedTokens: number;
+}
+
+type CurrentContextUsage = ReturnType<ExtensionContext["getContextUsage"]>;
+
+function hasMeasuredTokens(tokens: number | null | undefined): tokens is number {
+  return typeof tokens === "number" && tokens > 0;
+}
+
+function getApproximationNote(contextUsage: CurrentContextUsage): string | null {
+  if (contextUsage === undefined) return "Approximate (no usage data available)";
+  return hasMeasuredTokens(contextUsage.tokens)
+    ? null
+    : "Token count pending — send a message to refresh";
+}
+
 function applyScaling(
   categories: CategoryTokens,
   actualTokens: number | null,
@@ -227,20 +214,13 @@ function applyScaling(
   contextUsage:
     | { tokens: number | null; contextWindow: number; percent: number | null }
     | undefined,
-): {
-  categories: CategoryTokens;
-  scaled: boolean;
-  approximationNote: string | null;
-  totalTokens: number;
-} {
+): ScalingResult {
   let scaled = false;
-  let approximationNote: string | null = null;
-  const hasActualTotal = actualTokens !== null && actualTokens > 0;
-  const totalTokens = hasActualTotal ? actualTokens : rawTotal;
+  const hasActualTotal = hasMeasuredTokens(actualTokens);
+  const usedTokens = hasActualTotal ? actualTokens : rawTotal;
+  const approximationNote = getApproximationNote(contextUsage);
 
-  if (contextUsage === undefined) {
-    approximationNote = "Approximate (no usage data available)";
-  } else if (hasActualTotal && rawTotal > 0) {
+  if (hasActualTotal && rawTotal > 0) {
     const scale = actualTokens / rawTotal;
     categories.systemPrompt = Math.round(categories.systemPrompt * scale);
     categories.userMessages = Math.round(categories.userMessages * scale);
@@ -249,11 +229,9 @@ function applyScaling(
     categories.toolResults = Math.round(categories.toolResults * scale);
     categories.other = Math.round(categories.other * scale);
     scaled = true;
-  } else if (actualTokens === null || actualTokens === 0) {
-    approximationNote = "Token count pending — send a message to refresh";
   }
 
-  return { categories, scaled, approximationNote, totalTokens };
+  return { categories, scaled, approximationNote, usedTokens };
 }
 
 /**
@@ -508,18 +486,10 @@ function computeToolDefinitions(pi: ExtensionAPI): {
   };
 }
 
-function detectCompaction(branch: ReturnType<ExtensionContext["sessionManager"]["getBranch"]>): {
-  summarizedTurns: number;
-} | null {
-  const compactionEntry = getLatestCompactionEntry(branch);
-  if (!compactionEntry) return null;
-
-  const index = branch.findIndex((e) => e.id === compactionEntry.id);
-  const messagesBefore = branch
-    .slice(0, Math.max(0, index))
-    .filter((e) => e.type === "message").length;
-  const summarizedTurns = Math.floor(messagesBefore / 2);
-  return { summarizedTurns };
+function hasCompactionOnActiveBranch(
+  branch: ReturnType<ExtensionContext["sessionManager"]["getBranch"]>,
+): boolean {
+  return getLatestCompactionEntry(branch) !== null;
 }
 
 export function extractInjectedContextFiles(messages: AgentMessage[]): InjectedFileInfo[] {
@@ -556,22 +526,93 @@ export function extractInjectedContextFiles(messages: AgentMessage[]): InjectedF
   return Array.from(seen.values()).sort((a, b) => a.turn - b.turn || a.file.localeCompare(b.file));
 }
 
-export function analyzeContext(
+interface ContextFallback {
+  messages: AgentMessage[];
+  systemPromptText: string;
+}
+
+interface CapacityObservation {
+  branch: ReturnType<ExtensionContext["sessionManager"]["getBranch"]>;
+  contextUsage: CurrentContextUsage;
+  snapshot: ContextPressureSnapshot;
+  fallback?: ContextFallback;
+}
+
+interface ContextObservation extends ContextFallback {
+  scaling: ScalingResult;
+  snapshot: ContextPressureSnapshot;
+}
+
+function estimateContextTokens(fallback: ContextFallback): number {
+  return (
+    estimateTextTokens(fallback.systemPromptText) +
+    fallback.messages.reduce((total, message) => total + estimateMessageTokens(message), 0)
+  );
+}
+
+function collectContextFallback(
   ctx: ExtensionContext,
-  pi: ExtensionAPI,
-  cachedOptions: BuildSystemPromptOptions | undefined,
-  full = false,
-): ContextAnalysis {
+  branch: ReturnType<ExtensionContext["sessionManager"]["getBranch"]>,
+): ContextFallback {
+  return {
+    messages: buildSessionContext(branch).messages,
+    systemPromptText: ctx.getSystemPrompt(),
+  };
+}
+
+/**
+ * Observe the small shared capacity seam. It only walks messages when Pi has
+ * no measured usage total and an aggregate estimate is genuinely necessary.
+ */
+function observeCapacity(ctx: ExtensionContext): CapacityObservation {
   const branch = ctx.sessionManager.getBranch();
-  const apiView = buildSessionContext(branch);
   const contextUsage = ctx.getContextUsage();
-  const contextWindow = contextUsage?.contextWindow ?? 0;
-  const actualTokens = contextUsage?.tokens ?? null;
+  let fallback: ContextFallback | undefined;
+  let usedTokens: number;
+  if (hasMeasuredTokens(contextUsage?.tokens)) {
+    usedTokens = contextUsage.tokens;
+  } else {
+    fallback = collectContextFallback(ctx, branch);
+    usedTokens = estimateContextTokens(fallback);
+  }
+  const settings = SettingsManager.create(ctx.cwd, undefined, {
+    projectTrusted: ctx.isProjectTrusted(),
+  });
+  const capacity = analyzeContextCapacity({
+    contextWindow: contextUsage?.contextWindow ?? null,
+    usedTokens,
+    compactionEnabled: settings.getCompactionEnabled(),
+    configuredReserveTokens: settings.getCompactionReserveTokens(),
+    compacted: hasCompactionOnActiveBranch(branch),
+    approximationNote: getApproximationNote(contextUsage),
+  });
 
-  const systemPromptText = ctx.getSystemPrompt();
-  const categories = computeMessageCategories(apiView.messages);
-  categories.systemPrompt = estimateTextTokens(systemPromptText);
+  return {
+    branch,
+    contextUsage,
+    fallback,
+    snapshot: createContextPressureSnapshot(
+      ctx.model?.name ?? ctx.model?.id ?? "No model selected",
+      capacity,
+    ),
+  };
+}
+
+/** Return a constant-shape Context Pressure Snapshot without diagnostic attribution. */
+export function analyzeContextPressure(ctx: ExtensionContext): ContextPressureSnapshot {
+  return observeCapacity(ctx).snapshot;
+}
 
+/** Compose a full Context Usage Report from shared capacity and diagnostic attribution. */
+export function analyzeContext(
+  ctx: ExtensionContext,
+  pi: ExtensionAPI,
+  cachedOptions: BuildSystemPromptOptions | undefined,
+): ContextAnalysis {
+  const capacity = observeCapacity(ctx);
+  const fallback = capacity.fallback ?? collectContextFallback(ctx, capacity.branch);
+  const categories = computeMessageCategories(fallback.messages);
+  categories.systemPrompt = estimateTextTokens(fallback.systemPromptText);
   const rawTotal =
     categories.systemPrompt +
     categories.userMessages +
@@ -579,45 +620,33 @@ export function analyzeContext(
     categories.toolCalls +
     categories.toolResults +
     categories.other;
-
-  const scaling = applyScaling(categories, actualTokens, rawTotal, contextUsage);
-
-  const autocompactBuffer =
-    contextWindow > 0 ? SettingsManager.create(ctx.cwd).getCompactionReserveTokens() : 0;
-  const used =
-    scaling.categories.systemPrompt +
-    scaling.categories.userMessages +
-    scaling.categories.assistantMessages +
-    scaling.categories.toolCalls +
-    scaling.categories.toolResults +
-    scaling.categories.other;
-  const freeSpace = Math.max(0, contextWindow - used - autocompactBuffer);
-
+  const observation: ContextObservation = {
+    ...fallback,
+    scaling: applyScaling(
+      categories,
+      capacity.contextUsage?.tokens ?? null,
+      rawTotal,
+      capacity.contextUsage,
+    ),
+    snapshot: capacity.snapshot,
+  };
   const promptOptions = deriveOptionsFromSystemPrompt(ctx, cachedOptions);
   const breakdown = computeSystemPromptBreakdown(
     promptOptions,
-    systemPromptText,
-    scaling.categories.systemPrompt,
+    observation.systemPromptText,
+    observation.scaling.categories.systemPrompt,
     ctx.cwd,
   );
-  const injectedFiles = extractInjectedContextFiles(apiView.messages);
+  const injectedFiles = extractInjectedContextFiles(observation.messages);
   const toolDefinitions = computeToolDefinitions(pi);
-  const compaction = detectCompaction(branch);
-
-  const guidelineBullets = extractGuidelineBullets(extractGuidelinesSection(systemPromptText));
+  const guidelineBullets = extractGuidelineBullets(
+    extractGuidelinesSection(observation.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,
-      freeSpace,
-    },
+    ...observation.snapshot,
+    scaled: observation.scaling.scaled,
+    categories: observation.scaling.categories,
     systemPromptBreakdown: breakdown,
     injectedFiles,
     skills: breakdown.skills,
@@ -626,7 +655,6 @@ export function analyzeContext(
     guidelineSources: breakdown.guidelineSources,
     toolSnippetDetails: breakdown.toolSnippetDetails,
     toolDefinitions,
-    compaction,
     providerSections: collectProviderData(),
   };
 }

package/src/capacity.ts

@@ -0,0 +1,81 @@
+/**
+ * A small, point-in-time capacity reading without diagnostic attribution.
+ */
+export interface ContextCapacity {
+  contextWindow: number | null;
+  usedTokens: number;
+  usagePercent: number | null;
+  compactionEnabled: boolean;
+  reserveTokens: number;
+  headroomTokens: number | null;
+  pressurePercent: number | null;
+  compacted: boolean;
+  approximationNote: string | null;
+}
+
+/** Agent-facing, constant-shape reading of current context pressure. */
+export interface ContextPressureSnapshot extends ContextCapacity {
+  modelName: string;
+}
+
+/** Inputs that the shared capacity analysis derives from session state. */
+export interface ContextCapacityInput {
+  contextWindow: number | null;
+  usedTokens: number;
+  compactionEnabled: boolean;
+  configuredReserveTokens: number;
+  compacted: boolean;
+  approximationNote: string | null;
+}
+
+function roundPercentage(value: number): number {
+  return Math.round(value * 10) / 10;
+}
+
+/**
+ * Derive reserve-adjusted capacity without inspecting diagnostic inventories.
+ *
+ * The configured reserve affects capacity only while auto-compaction is enabled.
+ * This lets report and snapshot callers share exactly the same Active Context
+ * Limit, Headroom, and Pressure Percentage semantics.
+ */
+export function analyzeContextCapacity(input: ContextCapacityInput): ContextCapacity {
+  const contextWindow = input.contextWindow && input.contextWindow > 0 ? input.contextWindow : null;
+  const reserveTokens = input.compactionEnabled ? Math.max(0, input.configuredReserveTokens) : 0;
+  const activeLimit = contextWindow === null ? null : contextWindow - reserveTokens;
+  const hasUsableActiveLimit = activeLimit !== null && activeLimit > 0;
+
+  return {
+    contextWindow,
+    usedTokens: input.usedTokens,
+    usagePercent:
+      contextWindow === null ? null : roundPercentage((input.usedTokens / contextWindow) * 100),
+    compactionEnabled: input.compactionEnabled,
+    reserveTokens,
+    headroomTokens: activeLimit === null ? null : Math.max(0, activeLimit - input.usedTokens),
+    pressurePercent: hasUsableActiveLimit
+      ? roundPercentage((input.usedTokens / activeLimit) * 100)
+      : null,
+    compacted: input.compacted,
+    approximationNote: input.approximationNote,
+  };
+}
+
+/** Create the exact agent-facing Context Pressure Snapshot shape. */
+export function createContextPressureSnapshot(
+  modelName: string,
+  capacity: ContextCapacity,
+): ContextPressureSnapshot {
+  return {
+    modelName,
+    contextWindow: capacity.contextWindow,
+    usedTokens: capacity.usedTokens,
+    usagePercent: capacity.usagePercent,
+    compactionEnabled: capacity.compactionEnabled,
+    reserveTokens: capacity.reserveTokens,
+    headroomTokens: capacity.headroomTokens,
+    pressurePercent: capacity.pressurePercent,
+    compacted: capacity.compacted,
+    approximationNote: capacity.approximationNote,
+  };
+}