bermudis-pi-goodies 0.26.0 → 0.27.1

package/README.md

@@ -23,10 +23,17 @@ extensions. One entry point, thirteen independent features.
 
 ## Install
 
-After publishing the package to npm:
+First install, pinned to a published version:
 
 ```bash
-pi install npm:bermudis-pi-goodies@0.26.0
+pi install npm:bermudis-pi-goodies@0.27.1
+```
+
+Picking up a new release on an existing install (`pi install` is not the
+update path):
+
+```bash
+pi update --extensions
 ```
 
 Remove any old `bermudis-pi-goodies.ts` symlink before reloading Pi. Each
@@ -373,11 +380,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.1",
   "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

package/vision-core.ts

@@ -1,14 +1,16 @@
 /**
  * vision-core — pure logic for the `vision` tool.
  *
- * No pi imports: structural types stand in for pi's registry/model objects so
- * this module (and its tests) run under plain `bun` without a pi install.
+ * No pi runtime imports: structural types stand in for registry/model objects.
+ * The request context uses pi's types so incomplete replay messages cannot
+ * silently cross the completion boundary.
  * index.ts wires these against the real pi APIs.
  */
 import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, extname, join, resolve } from "node:path";
+import type { Context, Message } from "@earendil-works/pi-ai/compat";
 
 // --- structural stand-ins for pi types ---------------------------------------
 
@@ -16,6 +18,7 @@ import { dirname, extname, join, resolve } from "node:path";
 export interface ModelLike {
   id: string;
   provider: string;
+  api: string;
   input: string[];
 }
 
@@ -558,9 +561,10 @@ export const VISION_SYSTEM_PROMPT = [
 export function buildVisionContext(
   prompt: string,
   image: { data: string; mimeType: string },
+  model: ModelLike,
   history: StoredTurn[] = [],
-): object {
-  const past = history.flatMap((turn) => [
+): Context {
+  const past = history.flatMap<Message>((turn) => [
     {
       role: "user",
       content: [{ type: "text", text: turn.question }],
@@ -569,6 +573,21 @@ export function buildVisionContext(
     {
       role: "assistant",
       content: [{ type: "text", text: turn.answer }],
+      api: model.api,
+      provider: model.provider,
+      model: model.id,
+      stopReason: "stop",
+      // These are text-only replays, not the original provider responses.
+      // Zero usage makes Pi estimate this request's actual content instead of
+      // treating a previous request's token count as an authoritative prefix.
+      usage: {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        totalTokens: 0,
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+      },
       timestamp: Date.now(),
     },
   ]);
@@ -644,7 +663,7 @@ export interface VisionToolDeps {
   /** pi-ai completeSimple (injected so tests stub it). */
   complete(
     model: ModelLike,
-    context: object,
+    context: Context,
     options: {
       apiKey?: string;
       headers?: Record<string, string | null>;
@@ -760,6 +779,7 @@ export async function runVisionTool(
           data: image.data as string,
           mimeType: image.mimeType as string,
         },
+        transport.model,
         history,
       ),
       {

package/vision.ts

@@ -133,6 +133,13 @@ function questionPreview(prompt: unknown, cap: number): string {
   return head;
 }
 
+/** Expanded views show the raw truth: the whole prompt, uncapped — the cap
+ *  is a compact-view aid, and ctrl+o exists to reveal what was actually
+ *  asked (bash's expanded-command rule; multi-line renders multi-line). */
+function fullQuestion(prompt: unknown): string {
+  return typeof prompt === "string" ? prompt : "";
+}
+
 /** Answer text of a recorded vision result (its content is one text block). */
 function answerText(result: unknown): string {
   const content = (result as { content?: Array<{ text?: string }> } | undefined)
@@ -160,8 +167,10 @@ const visionBurstSpec = {
         // Read-view rule: info that is missing is skipped, never rendered as
         // junk (no `: ""` when a prompt is absent) — and long answers get the
         // same 12-line preview + "... N more lines" note as every other tool.
+        // Details render only when expanded, so questions show uncapped
+        // (same rule as bash's expanded details).
         const follow = e.args.followUp ? " (follow-up)" : "";
-        const q = questionPreview(e.args.prompt, 90);
+        const q = fullQuestion(e.args.prompt);
         const label = `— ${shortenPath(e.args.path || "...")}${follow}${q ? `: "${q}"` : ""}`;
         if (!e.result) return `\n${theme.fg("warning", `${label} (pending)`)}`;
         const txt = answerText(e.result);
@@ -170,9 +179,14 @@ const visionBurstSpec = {
       })
       .join("");
   },
-  soloHeader(args: any, theme: any) {
+  soloHeader(args: any, theme: any, ctx: any) {
     const follow = args.followUp ? theme.fg("muted", " (follow-up)") : "";
-    const q = questionPreview(args.prompt, 90);
+    // Expanded shows the full question, uncapped — the 90-char preview is a
+    // compact-view aid, and the whole point of ctrl+o is to reveal what was
+    // actually asked (same rule as bash's expanded command).
+    const q = ctx?.expanded
+      ? fullQuestion(args.prompt)
+      : questionPreview(args.prompt, 90);
     return `${theme.fg("toolTitle", theme.bold("vision"))} ${theme.fg("accent", shortenPath(args.path || "..."))}${follow}${q ? ` ${theme.fg("toolOutput", `"${q}"`)}` : ""}`;
   },
   soloExpanded(entry: any, _args: any, theme: any) {
@@ -367,18 +381,14 @@ export default function (pi: ExtensionAPI): void {
             ) as Promise<{ content: ContentBlockLike[]; isError?: boolean }>,
           readRaw: readRawImage,
           complete: (model, context, options) =>
-            completeSimple(
-              model as never,
-              context as never,
-              {
-                apiKey: options.apiKey,
-                headers: options.headers,
-                maxTokens: options.maxTokens,
-                signal: options.signal,
-                timeoutMs: 120_000,
-                maxRetries: 1,
-              } as never,
-            ) as Promise<never>,
+            completeSimple(model as never, context, {
+              apiKey: options.apiKey,
+              headers: options.headers,
+              maxTokens: options.maxTokens,
+              signal: options.signal,
+              timeoutMs: 120_000,
+              maxRetries: 1,
+            } as never) as Promise<never>,
         },
         (text) =>
           onUpdate?.({