bermudis-pi-goodies 0.26.0 → 0.27.0

package/README.md

@@ -26,7 +26,7 @@ extensions. One entry point, thirteen independent features.
 After publishing the package to npm:
 
 ```bash
-pi install npm:bermudis-pi-goodies@0.26.0
+pi install npm:bermudis-pi-goodies@0.27.0
 ```
 
 Remove any old `bermudis-pi-goodies.ts` symlink before reloading Pi. Each
@@ -373,11 +373,16 @@ session. `/side-exit` closes it and chooses what the main agent receives.
 How it works:
 
 - **Badge**: while a side session is open, the footer's model readout becomes
-  `side: (zai) glm-5.3 • max` — the provider-balance footer prepends the
-  badge to the stats line instead of adding a separate `side:` status line
-  (which remains the fallback when that footer is not mounted). The readout
-  tracks mid-side ctrl+l switches, and the badge clears on exit or when
-  switching to a session that is not in a side consultation.
+  `side: (zai) glm-5.3 • max · ~46k lensed` — the provider-balance footer
+  prepends the badge to the stats line instead of adding a separate `side:`
+  status line (which remains the fallback when that footer is not mounted).
+  The `~46k lensed` suffix is the estimated size of the request the lens will
+  actually send (quote + side turns, pi's own chars/4 estimator): pi's footer
+  context-usage figure estimates the raw session branch, which the lens then
+  rewrites at the wire, so it over-reports during side sessions. The suffix
+  is dropped first when the line gets tight. The readout tracks mid-side
+  ctrl+l switches, and the badge clears on exit or when switching to a
+  session that is not in a side consultation.
 - **Entry**: `/side` opens pi's own model selector (falls back to a plain
   selector when pi's internal runtime is not reachable; in headless modes pass
   the model explicitly as `/side provider/model-id[:level]`). The main agent's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bermudis-pi-goodies",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/bermudi/agent-extensions.git",

package/provider-balance.ts

@@ -32,6 +32,7 @@ import {
 import { getKiloCatalogStatus, type KiloCatalogStatus } from "./kilo.ts";
 import { logGoodiesEvent, reportFailure } from "./goodies-log.ts";
 import {
+  formatSideLensSuffix,
   getSideSessionModel,
   onSideBadgeChange,
   setMergedSideBadgeInstalled,
@@ -1306,11 +1307,13 @@ const SGR_SEQUENCE = /\x1b\[[0-9;:]*m/g;
 
 /**
  * Prepend a badge to the right-aligned model readout of the stats line pi's
- * FooterComponent produced: `side: (zai) glm-5.3 • max`. The line is built
- * as `<dim statsLeft><dim padding + model>` — split at the opener of the
- * final styled run (the last SGR sequence is its closer, so the opener is
- * the second-to-last), keep the left half verbatim (it may carry a colored
- * context percentage), and rebuild the right half around the badge.
+ * FooterComponent produced: `side: (zai) glm-5.3 • max · ~46k lensed`. The
+ * line is built as `<dim statsLeft><dim padding + model>` — split at the
+ * opener of the final styled run (the last SGR sequence is its closer, so
+ * the opener is the second-to-last), keep the left half verbatim (it may
+ * carry a colored context percentage), and rebuild the right half around
+ * the badge. A suffix that does not fit is dropped before the badge itself
+ * is ever truncated — the model name outranks the token estimate.
  *
  * Returns undefined when the line lacks that two-run shape — the caller then
  * leaves the line untouched and the /side badge falls back to a status line.
@@ -1322,6 +1325,7 @@ export function mergeSideBadgeIntoStatsLine(
   width: number,
   theme: FooterTheme,
   prefix = "side: ",
+  suffix = "",
 ): string | undefined {
   if (!line || width <= 0) return undefined;
   const runs = [...line.matchAll(SGR_SEQUENCE)];
@@ -1332,14 +1336,17 @@ export function mergeSideBadgeIntoStatsLine(
   const tail = stripTerminalSequences(line.slice(opener)).trim();
   if (!tail || !stripTerminalSequences(head).trim()) return undefined;
 
-  const labeled = `${prefix}${tail}`;
+  const withSuffix = `${prefix}${tail}${suffix}`;
+  const bare = `${prefix}${tail}`;
   const headWidth = visibleWidth(head);
   const room = width - headWidth - 2; // pi keeps ≥2 columns between the halves
   if (room <= 0) return undefined;
   const right =
-    visibleWidth(labeled) <= room
-      ? labeled
-      : truncateToWidth(labeled, room, "");
+    visibleWidth(withSuffix) <= room
+      ? withSuffix
+      : visibleWidth(bare) <= room
+        ? bare
+        : truncateToWidth(bare, room, "");
   const padding = " ".repeat(
     Math.max(2, width - headWidth - visibleWidth(right)),
   );
@@ -1781,6 +1788,8 @@ export default function providerBalance(
               lines[1],
               width,
               theme,
+              "side: ",
+              formatSideLensSuffix(),
             );
             if (statsLine !== undefined) {
               lines[1] = statsLine;

package/side-state.ts

@@ -54,6 +54,42 @@ export function getSideSessionModel(): SideModelRef | undefined {
   return activeModel;
 }
 
+let lensTokens: number | undefined;
+
+/**
+ * side.ts: estimated token size of the LENSED request (the quote + side
+ * turns actually sent to the side model), via pi's own chars/4 estimator
+ * so it stays comparable with the footer's raw-branch figure. Undefined on
+ * non-side branches — pi's footer estimate is correct there.
+ *
+ * Why: pi's footer context-usage and pre-send compaction threshold both
+ * estimate the RAW session projection; the side lens rewrites the request
+ * at the wire, after every estimator. The footer therefore over-reports
+ * while a side session is active. The badge carries this estimate as the
+ * honest counterpoint.
+ */
+export function setSideLensTokens(tokens: number | undefined): void {
+  if (lensTokens === tokens) return;
+  lensTokens = tokens;
+  emit();
+}
+
+export function getSideLensTokens(): number | undefined {
+  return lensTokens;
+}
+
+/** Badge suffix for the lensed estimate: " · ~46k lensed", or "" when off. */
+export function formatSideLensSuffix(): string {
+  if (lensTokens === undefined || lensTokens < 1_000) return "";
+  return ` · ~${formatSideLensTokens(lensTokens)} lensed`;
+}
+
+function formatSideLensTokens(tokens: number): string {
+  if (tokens >= 1_000_000) return `${(tokens / 1_000_000).toFixed(1)}M`;
+  if (tokens >= 10_000) return `${Math.round(tokens / 1_000)}k`;
+  return `${(tokens / 1_000).toFixed(1)}k`;
+}
+
 /** provider-balance: its footer now owns (or handed back) the stats line. */
 export function setMergedSideBadgeInstalled(installed: boolean): void {
   if (mergedInstalled === installed) return;
@@ -88,6 +124,7 @@ export function onSideBadgeChange(listener: () => void): () => void {
 /** Test-only: restore the pristine module state (undefined/false/false). */
 export function resetSideBadgeState(): void {
   activeModel = undefined;
+  lensTokens = undefined;
   mergedInstalled = false;
   mergedRendered = false;
   listeners.clear();

package/side.ts

@@ -28,9 +28,13 @@
  * limb that is ever resumed delivers only newer turns. v1 always starts a
  * fresh side limb, but the bookkeeping keeps that future-safe.
  *
- * Known cosmetic limitation: the footer's context-usage estimate reflects the
- * raw session branch, not the lens output, so it over-reports while a side
- * session is active.
+ * Known limitation: pi's footer context-usage estimate (and its pre-send
+ * compaction threshold) reflect the raw session branch, not the lens
+ * output — the footer over-reports while a side session is active, and
+ * premature auto-compaction is possible on large side consults (the lens
+ * is compaction-aware and survives it; the main limb is never touched).
+ * The side badge carries pi's own estimator applied to the lensed messages
+ * ("· ~46k lensed") as the honest counterpoint to the inflated figure.
  */
 
 import type {
@@ -43,15 +47,18 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import {
   ModelSelectorComponent,
+  estimateTokens,
   sessionEntryToContextMessages,
 } from "@earendil-works/pi-coding-agent";
 import { describeError, extractTextParts } from "./json-file.ts";
 import { buildTrajectory, renderTrajectory } from "./copy-trajectory.ts";
 import { logGoodiesEvent } from "./goodies-log.ts";
 import {
+  formatSideLensSuffix,
   getSideSessionModel,
   isMergedSideBadgeActive,
   onSideBadgeChange,
+  setSideLensTokens,
   setSideSessionModel,
   type SideModelRef,
 } from "./side-state.ts";
@@ -298,6 +305,22 @@ export function buildLensMessages(
   return messages;
 }
 
+/**
+ * Estimate the token size of the lensed request pi will actually send
+ * (quote + side-native messages), using pi's own chars/4 estimator so the
+ * number is comparable with the footer's raw-branch estimate. Undefined
+ * when markerIdx does not mark a side session.
+ */
+export function estimateLensedContextTokens(
+  awareEntries: readonly SessionEntry[],
+  rawBranch: readonly SessionEntry[],
+  markerIdx: number,
+): number | undefined {
+  const messages = buildLensMessages(awareEntries, rawBranch, markerIdx, []);
+  if (!messages) return undefined;
+  return messages.reduce((sum, message) => sum + estimateTokens(message), 0);
+}
+
 // ---------------------------------------------------------------------------
 // Handoff: what the main agent is given at exit
 // ---------------------------------------------------------------------------
@@ -511,7 +534,7 @@ export function applySideStatus(ctx: ExtensionContext): void {
   const model: SideModelRef | undefined = getSideSessionModel();
   const text =
     model && !isMergedSideBadgeActive()
-      ? `side: ${modelRef(model)}`
+      ? `side: ${modelRef(model)}${formatSideLensSuffix()}`
       : undefined;
   ctx.ui.setStatus("side", text);
 }
@@ -547,6 +570,26 @@ export function activeSideModel(
   return markerData.sideModel;
 }
 
+/**
+ * Refresh the badge's lensed-context estimate from the live branch —
+ * undefined on non-side branches, so the suffix also clears on exit and
+ * navigation. O(branch text) char counting: cheap per turn, far too hot
+ * for per-frame footer renders (those read the cached side-state value).
+ */
+function refreshSideLens(ctx: ExtensionContext): void {
+  const raw = ctx.sessionManager.getBranch();
+  const markerIdx = findSideBoundary(raw);
+  let tokens: number | undefined;
+  if (markerIdx !== -1) {
+    tokens = estimateLensedContextTokens(
+      ctx.sessionManager.buildContextEntries(),
+      raw,
+      markerIdx,
+    );
+  }
+  setSideLensTokens(tokens);
+}
+
 async function summarizeDelta(
   ctx: ExtensionCommandContext,
   sideModel: ModelRef,
@@ -627,6 +670,7 @@ export default function side(pi: ExtensionAPI): void {
       setSideSessionModel(undefined);
       applySideStatus(ctx);
     }
+    refreshSideLens(ctx);
   });
 
   // Restore the badge when a session resumes already on a side limb. The
@@ -650,8 +694,17 @@ export default function side(pi: ExtensionAPI): void {
       setSideSessionModel(undefined);
       applySideStatus(ctx);
     }
+    refreshSideLens(ctx);
   });
 
+  // The lensed-context estimate the badge carries: the quote is frozen at
+  // entry, so it only moves when the side limb grows, compaction rewrites
+  // the view, or navigation changes the limb. Non-side events are a cheap
+  // marker scan that ends in a no-op set.
+  pi.on("turn_start", (_event, ctx) => refreshSideLens(ctx));
+  pi.on("message_end", (_event, ctx) => refreshSideLens(ctx));
+  pi.on("session_compact", (_event, ctx) => refreshSideLens(ctx));
+
   // The footer-rendered badge needs a re-render when side state changes;
   // the status-line fallback needs re-applying when the merged footer
   // appears or disappears (install order between the two modules is not