Feed system-prompt/tool-schema overhead into the context estimate, fall back to it when a provider reports zero usage, and let compaction fire before the turn floor or between inference cycles when a tool result pushes context past the danger threshold

The status-bar meter previously read only provider-reported input+cache tokens with no fallback, so a provider that omits or zeroes usage pinned it at a stale or 0% reading while real occupancy climbed. The local estimator also never counted the system prompt or tool schemas sent on every request, understating even its own fallback. Compaction's minimum-turn floor and its inference.done-only recheck meant a single huge early turn or a large tool result mid-streak could blow past the model's context window before the governor was allowed to act. Also unified the three independent input+cacheRead+cacheWrite computations (compaction, the status-bar meter, and faremeter) behind one function so they can't silently diverge.

Author: TheGreatAxios

src/agent/compaction.test.ts

@@ -7,7 +7,7 @@ import type {
   TokenUsage,
 } from "@intx/types/runtime";
 import { createCompactionGovernor } from "./compaction.js";
-import { compactionThresholdFor } from "../provider/context-window.js";
+import { compactionThresholdFor, urgentCompactionThresholdFor } from "../provider/context-window.js";
 
 const capabilities = {
   infer: (options?: unknown) => ({ type: "infer", ...(options !== undefined ? { options } : {}) }),
@@ -255,4 +255,41 @@ describe("compaction governor", () => {
     expect(governor.interceptActions(inferenceDone(overThreshold), inferAction, capabilities)).toBeNull();
     expect(governor.interceptActions(toolDone(), [{ type: "reply", content: "x" }], capabilities)).toBeNull();
   });
+
+  test("bypasses the minimum-turn floor when a single turn is urgently over threshold", () => {
+    // Two turns is well under MIN_TURNS_TO_COMPACT, but reported usage alone
+    // is past the urgent threshold — a huge early file read or tool payload.
+    // Waiting for turn 7 here would risk a provider-side overflow first.
+    const governor = createCompactionGovernor(() => {});
+    const urgentTokens = urgentCompactionThresholdFor("m") + 1;
+    governor.noteInferenceDone(inferenceDone(urgentTokens), turnsOfLength(2, 1));
+
+    const actions = governor.interceptActions(toolDone(), inferAction, capabilities);
+    expect(actions).not.toBeNull();
+    expect(actions?.some((a) => a.type === "compact")).toBe(true);
+  });
+
+  test("still respects the minimum-turn floor when only mildly over threshold", () => {
+    // Same low turn count, but under the urgent threshold — the ordinary
+    // floor still applies.
+    const governor = createCompactionGovernor(() => {});
+    governor.noteInferenceDone(inferenceDone(overThreshold), turnsOfLength(2, 1));
+    expect(governor.interceptActions(toolDone(), inferAction, capabilities)).toBeNull();
+  });
+
+  test("arms on tool.done from a live estimate even when the last snapshot was under threshold", () => {
+    // inference.done reported a small usage (pending stays false), but the
+    // tool result that follows is itself large enough to blow past the
+    // urgent threshold before the next inference.done ever runs.
+    const governor = createCompactionGovernor(() => {});
+    governor.noteInferenceDone(inferenceDone(10), tenTurns);
+    expect(governor.interceptActions(toolDone(), inferAction, capabilities)).toBeNull();
+
+    const urgentChars = (urgentCompactionThresholdFor("m") + 1) * 4;
+    governor.syncFromTurns(turnsOfLength(1, urgentChars));
+
+    const actions = governor.interceptActions(toolDone(), inferAction, capabilities);
+    expect(actions).not.toBeNull();
+    expect(actions?.some((a) => a.type === "compact")).toBe(true);
+  });
 });

src/agent/compaction.ts

@@ -3,9 +3,14 @@ import type {
   ReactorAction,
   ReactorCapabilities,
   ReactorInboundEvent,
+  ToolDefinition,
 } from "@intx/types/runtime";
-import { compactionThresholdFor } from "../provider/context-window.js";
-import { createContextEstimate } from "./context-estimate.js";
+import {
+  compactionThresholdFor,
+  contextTokensFromUsage,
+  urgentCompactionThresholdFor,
+} from "../provider/context-window.js";
+import { createContextEstimate, estimateOverheadTokens } from "./context-estimate.js";
 
 const COMPACTOR_NAME = "pruning-compactor";
 const MIN_TURNS_TO_COMPACT = 6;
@@ -20,17 +25,30 @@ const MAX_OVERFLOW_RECOVERIES = 2;
 // would be worse than growing the context.
 export type CompactionGovernor = ReturnType<typeof createCompactionGovernor>;
 
-export function createCompactionGovernor(requestContinuation?: () => void) {
+export function createCompactionGovernor(
+  requestContinuation?: () => void,
+  systemPrompt = "",
+  toolDefinitions: readonly ToolDefinition[] = [],
+) {
   let pending = false;
   let idlePending = false;
   let postCompactInfer = false;
   let overflowRecoveries = 0;
+  // Set whenever the arming decision fell back to the local estimate because
+  // the provider omitted usage or reported zero, so callers rendering a meter
+  // can flag the number as approximate instead of implying provider-grade
+  // precision.
+  let usingEstimate = false;
+  // Model of the last inference.done turn, kept for live re-checks between
+  // inference cycles (see interceptActions) where the event carries no model.
+  let lastModel: string | undefined;
 
-  // Running local estimate of the turns we send. Providers that omit usage or
-  // report zero leave the proactive path blind; the estimate fills that gap.
-  // When the provider reports real usage we prefer it so a coarse local count
-  // cannot thrash against a trustworthy signal.
-  const estimate = createContextEstimate();
+  // Running local estimate of the turns we send, plus the fixed system-prompt
+  // and tool-schema overhead every request carries. Providers that omit usage
+  // or report zero leave the proactive path blind; the estimate fills that
+  // gap. When the provider reports real usage we prefer it so a coarse local
+  // count cannot thrash against a trustworthy signal.
+  const estimate = createContextEstimate(estimateOverheadTokens(systemPrompt, toolDefinitions));
 
   // Re-sync after turn appends, tool results, and compaction rewrites. Callers
   // pass the full turn list so the estimate stays accurate without incremental
@@ -46,25 +64,42 @@ export function createCompactionGovernor(requestContinuation?: () => void) {
     overflowRecoveries = 0;
     if (requestContinuation === undefined) return;
     syncFromTurns(turns);
-    const reportedTokens = event.usage?.input ?? 0;
-    const contextTokens = reportedTokens > 0 ? reportedTokens : estimate.tokens;
+    lastModel = event.source?.model;
+    const reportedTokens = contextTokensFromUsage(event.usage);
+    usingEstimate = reportedTokens <= 0;
+    const contextTokens = usingEstimate ? estimate.tokens : reportedTokens;
     // Assign, don't OR: an under-threshold follow-up must disarm a sticky pending
     // left from an earlier over-threshold turn (e.g. after the provider reports
     // real usage that lands below the threshold).
+    //
+    // The turn-count floor exists to skip compacting a history too short to
+    // meaningfully shrink, but a single early turn (one huge file read or
+    // tool payload) can blow past the urgent threshold well before the floor
+    // is met — in that case waiting is worse than compacting a short history,
+    // so the floor is bypassed.
     pending =
-      contextTokens > compactionThresholdFor(event.source?.model) &&
-      turns.length > MIN_TURNS_TO_COMPACT;
+      contextTokens > compactionThresholdFor(lastModel) &&
+      (turns.length > MIN_TURNS_TO_COMPACT || contextTokens > urgentCompactionThresholdFor(lastModel));
   }
 
   // Compaction waits for the natural pause between a tool batch finishing and
   // the follow-up infer: the infer is dropped from the action set, the compact
   // cycle runs, and the continuation message re-enters inference.
+  //
+  // `pending` reflects the snapshot as of the last inference.done, which
+  // predates any tool results produced by that turn. A large tool result can
+  // push the live estimate past the urgent threshold before the next
+  // inference.done ever runs, so this also re-checks the live estimate
+  // (already re-synced this cycle by the director before calling here)
+  // rather than trusting a potentially stale `pending`.
   function interceptActions(
     event: ReactorInboundEvent,
     actions: ReactorAction[],
     capabilities: ReactorCapabilities,
   ): ReactorAction[] | null {
-    if (!pending || event.type !== "tool.done") return null;
+    if (event.type !== "tool.done") return null;
+    const urgentNow = estimate.tokens > urgentCompactionThresholdFor(lastModel);
+    if (!pending && !urgentNow) return null;
     if (!actions.some((a) => a.type === "infer")) return null;
     pending = false;
     postCompactInfer = true;
@@ -140,6 +175,12 @@ export function createCompactionGovernor(requestContinuation?: () => void) {
     get estimatedTokens(): number {
       return estimate.tokens;
     },
+    // True once the provider has omitted or zeroed usage on the current
+    // turn, so a status-bar meter reading this can mark itself approximate
+    // rather than silently understating a real number.
+    get usingEstimate(): boolean {
+      return usingEstimate;
+    },
     syncFromTurns,
     noteInferenceDone,
     noteIdleTurn,

src/agent/context-estimate.test.ts

@@ -1,10 +1,11 @@
 import { describe, expect, test } from "bun:test";
-import type { ContentBlock, ConversationTurn, MediaSource } from "@intx/types/runtime";
+import type { ContentBlock, ConversationTurn, MediaSource, ToolDefinition } from "@intx/types/runtime";
 import {
   createContextEstimate,
   estimateContentBlockTokens,
   estimateContextTokens,
   estimateMediaSourceTokens,
+  estimateOverheadTokens,
   estimateTokensFromChars,
 } from "./context-estimate.js";
 
@@ -85,7 +86,30 @@ describe("estimateContextTokens", () => {
   });
 });
 
+describe("estimateOverheadTokens", () => {
+  test("counts the system prompt and every tool's name, description, and schema", () => {
+    const systemPrompt = "x".repeat(40);
+    const tools: ToolDefinition[] = [
+      { name: "run_shell", description: "y".repeat(20), inputSchema: { command: "string" } },
+    ];
+    const expectedChars =
+      40 + "run_shell".length + 20 + JSON.stringify({ command: "string" }).length;
+    expect(estimateOverheadTokens(systemPrompt, tools)).toBe(estimateTokensFromChars(expectedChars));
+  });
+
+  test("is zero for an empty prompt and no tools", () => {
+    expect(estimateOverheadTokens("", [])).toBe(0);
+  });
+});
+
 describe("createContextEstimate", () => {
+  test("folds a fixed overhead into every sync", () => {
+    const estimate = createContextEstimate(100);
+    expect(estimate.tokens).toBe(100);
+    expect(estimate.syncFromTurns([textTurn("xxxx")])).toBe(101);
+    expect(estimate.tokens).toBe(101);
+  });
+
   test("re-syncs from the full turn list after each append", () => {
     const estimate = createContextEstimate();
     expect(estimate.tokens).toBe(0);

src/agent/context-estimate.ts

@@ -5,7 +5,12 @@
 // tool payloads, images) so proactive compaction still has a signal. This is
 // a lower bound: system prompt, tool schemas, and framing are not counted.
 
-import type { ContentBlock, ConversationTurn, MediaSource } from "@intx/types/runtime";
+import type {
+  ContentBlock,
+  ConversationTurn,
+  MediaSource,
+  ToolDefinition,
+} from "@intx/types/runtime";
 
 const CHARS_PER_TOKEN = 4;
 
@@ -77,17 +82,35 @@ export function estimateContextTokens(turns: readonly ConversationTurn[]): numbe
   return total;
 }
 
+// The system prompt and tool schemas ride on every request the same way turns
+// do, but they never appear in `turns` — they're framing the harness supplies
+// out of band. Without this, the estimate undercounts by whatever AGENTS.md
+// and the active tool roster cost, which is often tens of thousands of tokens
+// before a single turn is sent.
+export function estimateOverheadTokens(
+  systemPrompt: string,
+  toolDefinitions: readonly ToolDefinition[],
+): number {
+  let chars = systemPrompt.length;
+  for (const tool of toolDefinitions) {
+    chars += tool.name.length + tool.description.length + JSON.stringify(tool.inputSchema).length;
+  }
+  return estimateTokensFromChars(chars);
+}
+
 // Mutable running estimate. Callers re-sync from the full turn list after each
 // append so compaction rewrites and tool results stay accurate without
-// incremental add/subtract bookkeeping.
+// incremental add/subtract bookkeeping. `overheadTokens` is fixed per session
+// (system prompt + tool schemas do not change turn to turn) and is folded into
+// every sync so the total tracks what actually goes out on the wire.
 export type ContextEstimate = ReturnType<typeof createContextEstimate>;
 
-export function createContextEstimate() {
-  let tokens = 0;
+export function createContextEstimate(overheadTokens = 0) {
+  let tokens = overheadTokens;
   let turnCount = 0;
 
   function syncFromTurns(turns: readonly ConversationTurn[]): number {
-    tokens = estimateContextTokens(turns);
+    tokens = overheadTokens + estimateContextTokens(turns);
     turnCount = turns.length;
     return tokens;
   }

src/agent/director.ts

@@ -361,7 +361,7 @@ class ChatDirectorImpl extends DefaultDirector {
     this.onActivateTools = onActivateTools;
     this.workflowCoordinator = workflowCoordinator;
     this.onTasksChange = onTasksChange;
-    this.compaction = createCompactionGovernor(requestContinuation);
+    this.compaction = createCompactionGovernor(requestContinuation, systemPrompt, toolDefinitions);
     this.modelFamilyPolicy = modelFamilyPolicy ?? resolveModelFamilyPolicy({ providerName: "" });
   }
 
@@ -385,6 +385,13 @@ class ChatDirectorImpl extends DefaultDirector {
     return [...this.tasks];
   }
 
+  // The status bar's context meter falls back to this when a provider omits
+  // or zeroes usage on the latest turn — a local lower-then-corrected bound
+  // beats displaying a number the provider never actually reported.
+  getContextEstimate(): { tokens: number; isEstimate: boolean } {
+    return { tokens: this.compaction.estimatedTokens, isEstimate: this.compaction.usingEstimate };
+  }
+
   private openTaskIds(): string[] {
     return this.tasks
       .filter((t) => t.status === "todo" || t.status === "doing")
@@ -796,4 +803,5 @@ export interface ChatDirector extends ReactorDirector {
   setGoalGovernor(goal: GoalGovernor | undefined): void;
   getGoalGovernor(): GoalGovernor | undefined;
   getTasks(): Task[];
+  getContextEstimate(): { tokens: number; isEstimate: boolean };
 }

src/cost/cost-summary.test.ts

@@ -81,6 +81,11 @@ describe("formatStatusBarSegments", () => {
     expect(segments.contextLabel).toBe("Ctx --%");
     expect(segments.contextPercentUsed).toBeNull();
   });
+
+  it("flags an estimated context percentage with a tilde", () => {
+    const summary = buildCostSummary({ ...baseInput, contextIsEstimate: true });
+    expect(formatStatusBarSegments(summary).contextLabel).toBe("Ctx ~50%");
+  });
 });
 
 describe("formatCostCommandOutput", () => {
@@ -116,4 +121,9 @@ describe("formatCostCommandOutput", () => {
     const summary = buildCostSummary(baseInput);
     expect(formatCostCommandOutput(summary)).toContain("Context: 64000/unknown (--%)");
   });
+
+  it("flags an estimated context percentage with a tilde", () => {
+    const summary = buildCostSummary({ ...baseInput, contextIsEstimate: true });
+    expect(formatCostCommandOutput(summary)).toContain("(~50%)");
+  });
 });

src/cost/cost-summary.ts

@@ -17,6 +17,11 @@ export type CostSummaryInput = {
   outputTokens: number;
   cacheReadTokens: number;
   contextTokens: number;
+  // True when contextTokens came from the local character-count estimate
+  // because the provider omitted or zeroed usage on the latest turn, rather
+  // than from provider-reported usage. Lets the display flag the number as
+  // approximate instead of implying provider-grade precision.
+  contextIsEstimate?: boolean;
 };
 
 export type CostSummary = CostSummaryInput & {
@@ -53,8 +58,11 @@ export type StatusBarCostSegments = {
   contextPercentUsed: number | null;
 };
 
-function formatContextPercent(percent: number | null): string {
-  return percent === null ? "--%" : `${String(percent)}%`;
+function formatContextPercent(percent: number | null, isEstimate: boolean): string {
+  if (percent === null) return "--%";
+  // "~" flags a locally estimated number so the operator doesn't read it as
+  // provider-confirmed — see contextIsEstimate on CostSummaryInput.
+  return `${isEstimate ? "~" : ""}${String(percent)}%`;
 }
 
 // Status bar space is tight, so cost is omitted entirely (not shown as $0 or
@@ -64,7 +72,7 @@ function formatContextPercent(percent: number | null): string {
 export function formatStatusBarSegments(summary: CostSummary): StatusBarCostSegments {
   return {
     ...(summary.costHiddenReason === null ? { costLabel: summary.formattedCost } : {}),
-    contextLabel: `Ctx ${formatContextPercent(summary.contextPercentUsed)}`,
+    contextLabel: `Ctx ${formatContextPercent(summary.contextPercentUsed, summary.contextIsEstimate ?? false)}`,
     contextPercentUsed: summary.contextPercentUsed,
   };
 }
@@ -84,7 +92,7 @@ export function formatCostCommandOutput(summary: CostSummary): string {
       ? `Cost: ${summary.formattedCost}`
       : `Cost: hidden (${HIDDEN_REASON_TEXT[summary.costHiddenReason]})`,
     `Tokens: ${String(summary.inputTokens)} in / ${String(summary.outputTokens)} out / ${String(summary.cacheReadTokens)} cache-read`,
-    `Context: ${String(summary.contextTokens)}/${window} (${formatContextPercent(summary.contextPercentUsed)})`,
+    `Context: ${String(summary.contextTokens)}/${window} (${formatContextPercent(summary.contextPercentUsed, summary.contextIsEstimate ?? false)})`,
   ];
   return lines.join("\n");
 }

src/cost/faremeter.ts

@@ -1,6 +1,7 @@
 import type { TokenUsage } from "@intx/types/runtime";
 
 import { lookupModelPricing, type ModelPricing, type PricingCache } from "./pricing-fetcher.js";
+import { contextTokensFromUsage } from "../provider/context-window.js";
 
 export type FaremeterConfig = {
   inputPricePerToken: number;
@@ -60,7 +61,7 @@ export function createFaremeter(config: CreateFaremeterConfig = {}): Faremeter {
   return {
     addUsage(usage: TokenUsage): void {
       const { inputPricePerToken, outputPricePerToken, cacheReadPricePerToken } = pricesFor();
-      lastContextSize = usage.input + usage.cacheRead + usage.cacheWrite;
+      lastContextSize = contextTokensFromUsage(usage);
       outputTokens += usage.output + usage.thinking;
       totalCost += usage.input * inputPricePerToken + usage.output * outputPricePerToken + usage.cacheRead * cacheReadPricePerToken;
     },