pi-condense 2.10.6 → 2.11.1

package/CHANGELOG.md

@@ -7,6 +7,18 @@ Published to npm as [`pi-condense`](https://www.npmjs.com/package/pi-condense) (
 Pushing a `vX.Y.Z` tag triggers `.github/workflows/release.yml`, which runs the tests and
 publishes via OIDC trusted publishing. See `.agents/skills/release/SKILL.md`.
 
+## [2.11.1] - 2026-09-29
+
+### Fixed
+
+- The frontier-gap metric prices image blocks at a flat estimate instead of counting base64 as text, so screenshot reads no longer trigger a premature frontier-gap flush that prunes images before the model sees them.
+
+## [2.11.0] - 2026-09-24
+
+### Added
+
+- **Per-request image cap (`maxImagesPerRequest`).** Every image a model has seen stays in the transcript, so a session that reads many images eventually sends more than a provider accepts in one request - one gateway answers `Too many images in request: 31 > 30` - and then fails on every request, including after a resume. When set, the `context` handler replaces the oldest `image` blocks with a text note once a request carries more than N, in steps of half of N so the prompt prefix - and with it the provider's prompt cache - changes only once per step; the session file is untouched. It runs even with `enabled: false`, since it guards request validity rather than context size. Default `null` applies the built-in limit of the model's wire API - `100` for `anthropic-messages`, the documented Anthropic maximum; no cap for other APIs - and a number overrides it for every API. Config-file-only.
+
 ## [2.10.6] - 2026-09-19
 
 ### Fixed

package/README.md

@@ -169,6 +169,7 @@ Settings live under `contextPrune` in `<agent-dir>/settings.json` (`$PI_CODING_A
 | `pruneOn` | `agent-message` | Trigger mode - see Architecture above |
 | `autoBudgetThreshold` | `null` | Fraction (e.g. `0.8`) of the context window that force-flushes everything regardless of `pruneOn`; the trigger point is capped at 300k tokens |
 | `frontierGapThresholdTokens` | `null` | Opt-in absolute-token flush trigger: fires at `turn_end` once the un-pruned tail past the prune frontier reaches N tokens, regardless of window size; recommended starting value `80000` |
+| `maxImagesPerRequest` | `null` | Once a request carries more than N images, the oldest become a text note (in cache-friendly steps of half of N) so a long session stays under a provider's per-request image limit; applies even with pruning off. `null` = built-in limit for the model's API (Anthropic Messages: 100; others: no cap); a number overrides it for every API |
 | `protectedTools` / `protectedPaths` | `[]` / `["**/skills/**/*.md", "**/gauntlet-overrides.md"]` | Tool names / path globs that are never summarized; only the newest read per protected path stays verbatim (older reads of the same path are stubbed once the prompt cache is cold anyway) |
 | `spillThreshold` | `65536` | Chars above which a single oversized result spills straight to a sidecar file |
 

package/index.ts

@@ -15,6 +15,7 @@
 
 import type { ExtensionAPI, SessionEntry } from "@earendil-works/pi-coding-agent";
 import { loadConfig } from "./src/config.js";
+import { capImages, imageLimitFor } from "./src/image-cap.js";
 import { captureBatch, captureUnindexedBatchesFromSession, deriveLiveTurnIndex, groupBatchesByMode, projectBranchMessages } from "./src/batch-capture.js";
 import { summarizeBatch, summarizeBatches, summarizeRange } from "./src/summarizer.js";
 import { FallbackController } from "./src/summarizer-fallback.js";
@@ -1041,11 +1042,22 @@ export default function (pi: ExtensionAPI) {
 
   // ── context: prune summarized tool results from next LLM call ─────────────
   pi.on("context", async (event, ctx) => {
-    if (!currentConfig.value.enabled) return undefined;
-
     let messages = event.messages;
     let changed = false;
 
+    // Request-validity guard, independent of `enabled`: a transcript past the
+    // provider's per-request image limit fails every request until trimmed.
+    const imageCap = imageLimitFor(currentConfig.value.maxImagesPerRequest, ctx.model?.api);
+    if (imageCap !== null) {
+      const capped = capImages(messages, imageCap);
+      if (capped) {
+        messages = capped;
+        changed = true;
+      }
+    }
+
+    if (!currentConfig.value.enabled) return changed ? { messages } : undefined;
+
     // pruneMessages is the single source of truth for "is there work to do".
     // It returns the original array reference (pruned: false) only when none of
     // the five phases changed anything; index/registry emptiness alone does not

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-condense",
-  "version": "2.10.6",
+  "version": "2.11.1",
   "description": "Pi coding-agent extension that summarizes completed tool-call batches, replaces raw outputs with short stubs, compresses closed tool-call chains, and recovers any original on demand via context_tree_query.",
   "author": "Jacek Juraszek",
   "license": "MIT",

package/src/config.test.ts

@@ -176,6 +176,28 @@ describe("loadConfig frontierGapThresholdTokens normalization", () => {
   });
 });
 
+describe("loadConfig maxImagesPerRequest normalization", () => {
+  it("defaults to null when unset", async () => {
+    await writeContextPrune({});
+    const config = await loadConfig();
+    expect(config.maxImagesPerRequest).toBeNull();
+  });
+
+  it("floors a fractional value", async () => {
+    await writeContextPrune({ maxImagesPerRequest: 20.9 });
+    const config = await loadConfig();
+    expect(config.maxImagesPerRequest).toBe(20);
+  });
+
+  it("falls back to null for 0, a value below 1, negative, Infinity, or a string", async () => {
+    for (const value of [0, 0.5, -3, Infinity, "20"]) {
+      await writeContextPrune({ maxImagesPerRequest: value });
+      const config = await loadConfig();
+      expect(config.maxImagesPerRequest).toBeNull();
+    }
+  });
+});
+
 describe("saveConfig fails closed (#15)", () => {
   const config: ContextPruneConfig = { ...DEFAULT_CONFIG, enabled: false };
 

package/src/config.ts

@@ -112,6 +112,12 @@ function normalize(existing: Partial<ContextPruneConfig>): ContextPruneConfig {
       merged.frontierGapThresholdTokens > 0
         ? Math.floor(merged.frontierGapThresholdTokens)
         : DEFAULT_CONFIG.frontierGapThresholdTokens,
+    maxImagesPerRequest:
+      typeof merged.maxImagesPerRequest === "number" &&
+      Number.isFinite(merged.maxImagesPerRequest) &&
+      merged.maxImagesPerRequest >= 1
+        ? Math.floor(merged.maxImagesPerRequest)
+        : DEFAULT_CONFIG.maxImagesPerRequest,
   };
 }
 

package/src/context-metrics.test.ts

@@ -260,6 +260,22 @@ describe("computeContextMetrics", () => {
     expect(result.frontierGapTokens).toBe(expected);
   });
 
+  test("frontierGapTokens: image blocks use a flat estimate instead of base64 length", () => {
+    const msgs = [userMsg(100), assistantWithTools(200, ["tc1", "tc2", "tc3"])];
+    for (let i = 0; i < 3; i++) {
+      const result = toolResult(300 + i, `tc${i + 1}`, "read", "screenshot");
+      result.content.push({ type: "image", data: "A".repeat(137000), mimeType: "image/png" });
+      msgs.push(result);
+    }
+    const expected = msgs.slice(2).reduce((sum, msg) => {
+      const stub = { ...msg, content: msg.content.map((block: any) => block.type === "image" ? { type: "image" } : block) };
+      return sum + Math.round((JSON.stringify(stub).length + 1600 * 4) / 4);
+    }, 0);
+    const result = computeContextMetrics(msgs, null, noSummarized, noProtected);
+    expect(result.frontierGapTokens).toBe(expected);
+    expect(result.frontierGapTokens).toBeLessThan(20000);
+  });
+
   test("frontierGapTokens: boundary mid-turn split excludes at-or-before calls, includes later calls in same turn", () => {
     const msgs = [userMsg(100), assistantWithTools(200, ["tc1", "tc2"]), toolResult(300, "tc1"), toolResult(310, "tc2")];
     const frontier = fullFrontier({ lastAttemptedToolCallId: "tc1", lastAttemptedTurnIndex: 0 });

package/src/context-metrics.ts

@@ -2,8 +2,17 @@ import { detectChains, isChainAnchorCustom } from "./chain-detector.js";
 import { occKey, resultTimestampOf } from "./occurrence-key.js";
 import type { ContextMetricsSnapshot, PruneFrontier } from "./types.js";
 
+const IMAGE_TOKEN_ESTIMATE = 1600;
+
 function charsOf(msg: any): number {
-  return JSON.stringify(msg).length;
+  if (!Array.isArray(msg.content)) return JSON.stringify(msg).length;
+  let imageCount = 0;
+  const content = msg.content.map((block: any) => {
+    if (block?.type !== "image") return block;
+    imageCount++;
+    return { type: "image" };
+  });
+  return JSON.stringify({ ...msg, content }).length + imageCount * IMAGE_TOKEN_ESTIMATE * 4;
 }
 
 function tokensOf(msg: any): number {

package/src/image-cap.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from "bun:test";
+import { IMAGE_OMITTED_NOTE, capImages, imageLimitFor } from "./image-cap.js";
+
+const image = (n: number) => ({ type: "image", data: `img${n}`, mimeType: "image/png" });
+const imagesOf = (messages: any[]) =>
+  messages.flatMap((m) => (Array.isArray(m.content) ? m.content : [])).filter((b: any) => b.type === "image");
+
+describe("capImages", () => {
+  const reads = (count: number) =>
+    Array.from({ length: count }, (_, n) => ({
+      role: "toolResult",
+      content: [{ type: "text", text: "read" }, image(n)],
+    }));
+
+  it("omits the oldest images once over the cap, in steps of half the cap", () => {
+    const out = capImages(reads(31), 30)!;
+    expect(imagesOf(out).map((b: any) => b.data)).toEqual(Array.from({ length: 16 }, (_, n) => `img${n + 15}`));
+    expect(out[0].content[1]).toEqual({ type: "text", text: IMAGE_OMITTED_NOTE });
+    expect(out[0].content[0]).toEqual({ type: "text", text: "read" });
+  });
+
+  it("keeps the omitted prefix stable while new images arrive within a step", () => {
+    const omitted = (count: number) =>
+      (capImages(reads(count), 20) ?? reads(count)).filter((m: any) => m.content[1].type === "text").length;
+    expect([20, 21, 25, 30, 31, 40, 41].map(omitted)).toEqual([0, 10, 10, 10, 20, 20, 30]);
+  });
+
+  it("counts images within one message newest-last", () => {
+    const out = capImages([{ role: "user", content: [image(1), image(2), image(3)] }], 2)!;
+    expect(out[0].content.map((b: any) => b.data ?? b.text)).toEqual([IMAGE_OMITTED_NOTE, "img2", "img3"]);
+  });
+
+  it("does not mutate its input", () => {
+    const messages = [{ role: "user", content: [image(1), image(2)] }];
+    capImages(messages, 1);
+    expect(imagesOf(messages)).toHaveLength(2);
+  });
+
+  it("returns undefined when the request is already under the cap", () => {
+    expect(capImages([{ role: "user", content: [image(1)] }, { role: "assistant", content: "text" }], 5)).toBeUndefined();
+  });
+});
+
+describe("imageLimitFor", () => {
+  it("prefers the configured number over the built-in", () => {
+    expect(imageLimitFor(30, "anthropic-messages")).toBe(30);
+  });
+
+  it("falls back to the built-in Anthropic Messages limit", () => {
+    expect(imageLimitFor(null, "anthropic-messages")).toBe(100);
+  });
+
+  it("returns null for an API without a built-in limit or no model", () => {
+    expect(imageLimitFor(null, "openai-completions")).toBeNull();
+    expect(imageLimitFor(null, undefined)).toBeNull();
+  });
+});

package/src/image-cap.ts

@@ -0,0 +1,57 @@
+/**
+ * Per-request image cap (`maxImagesPerRequest`).
+ *
+ * Providers reject a request carrying more images than their limit, and every
+ * image a model has seen stays in the transcript, so a long session can cross
+ * the limit and then fail on every request. Once a request carries more than
+ * `max` images, `capImages` replaces the oldest ones with a text note, in steps
+ * of half the cap so the prompt prefix changes rarely. It never mutates its
+ * input; it returns `undefined` when nothing changes.
+ */
+
+export const IMAGE_OMITTED_NOTE =
+  "[earlier image omitted from this request: over maxImagesPerRequest; re-read the file or re-attach it to view it]";
+
+// Documented per-request limits of first-party wire APIs (Anthropic Messages:
+// 100 images per request). Keyed by `api`, not `provider`: the limit is enforced
+// by the protocol endpoint, whichever provider fronts it. Unlisted APIs
+// (OpenAI 1,500, Gemini 3,600) sit far above any realistic transcript.
+const BUILTIN_IMAGE_LIMITS: Record<string, number> = { "anthropic-messages": 100 };
+
+/** The effective cap: an explicit `maxImagesPerRequest` wins, else the built-in limit for the model's API. */
+export function imageLimitFor(configured: number | null, api: string | undefined): number | null {
+  if (configured !== null) return configured;
+  return api !== undefined ? (BUILTIN_IMAGE_LIMITS[api] ?? null) : null;
+}
+
+type Block = { type?: unknown };
+
+export function capImages<M extends object>(messages: M[], max: number): M[] | undefined {
+  const total = messages.reduce((n, m) => {
+    const content = (m as { content?: unknown }).content;
+    return n + (Array.isArray(content) ? content.filter((b) => (b as Block)?.type === "image").length : 0);
+  }, 0);
+  if (total <= max) return undefined;
+  // Omit the oldest images in steps of half the cap, not one per new image:
+  // the omitted set then changes once per `step` new images, so the prompt
+  // prefix (and the provider's prompt cache) stays stable in between.
+  const step = Math.max(1, Math.ceil(max / 2));
+  let toOmit = Math.min(total, Math.ceil((total - max) / step) * step);
+  let result: M[] | undefined;
+  for (let i = 0; i < messages.length && toOmit > 0; i++) {
+    const content = (messages[i] as { content?: unknown }).content;
+    if (!Array.isArray(content)) continue;
+    let replaced: Block[] | undefined;
+    for (let j = 0; j < content.length && toOmit > 0; j++) {
+      if ((content[j] as Block)?.type !== "image") continue;
+      replaced ??= content.slice() as Block[];
+      replaced[j] = { type: "text", text: IMAGE_OMITTED_NOTE } as Block;
+      toOmit--;
+    }
+    if (replaced) {
+      result ??= messages.slice();
+      result[i] = { ...messages[i], content: replaced } as M;
+    }
+  }
+  return result;
+}

package/src/types.ts

@@ -421,6 +421,15 @@ export interface ContextPruneConfig {
    * null (default) disables. Config-file-only — no settings overlay row.
    */
   frontierGapThresholdTokens: number | null;
+  /**
+   * Request-validity guard: keep only the newest N image blocks in each
+   * outgoing request and replace older ones with a text note, so a long
+   * session never exceeds a provider's per-request image limit. Applies even
+   * when `enabled` is false. null (default) uses the built-in limit for the
+   * model's API (`anthropic-messages`: 100; other APIs: no cap).
+   * Config-file-only.
+   */
+  maxImagesPerRequest: number | null;
 }
 
 /**
@@ -581,6 +590,7 @@ export const DEFAULT_CONFIG: ContextPruneConfig = {
   spillPreviewBytes: 2048,
   budgetTurnDelta: null,
   frontierGapThresholdTokens: null,
+  maxImagesPerRequest: null,
 };
 
 // ── Captured batch ─────────────────────────────────────────────────────────