mirror of
https://github.com/teamchong/pxpipe.git
synced 2026-07-22 02:02:51 +02:00
Steven Chong
2238 lines
100 KiB
TypeScript
2238 lines
100 KiB
TypeScript
/**
|
||
* Request-body transformer. Extracts the static system prompt + tool definitions,
|
||
* renders them as PNG image blocks, and rewrites the body to reference those images —
|
||
* saving 65-73% input tokens while preserving reasoning quality.
|
||
*/
|
||
|
||
import type {
|
||
ContentBlock,
|
||
ImageBlock,
|
||
Message,
|
||
MessagesRequest,
|
||
SystemField,
|
||
TextBlock,
|
||
ToolDef,
|
||
ToolResultBlock,
|
||
ToolUseBlock,
|
||
} from './types.js';
|
||
import {
|
||
renderTextToPngs,
|
||
renderTextToPngsMultiCol,
|
||
reflow,
|
||
maxFittingCols,
|
||
shrinkColsToContent,
|
||
MAX_HEIGHT_PX,
|
||
NL_SENTINEL,
|
||
neutralizeSentinel,
|
||
PAD_X,
|
||
PAD_Y,
|
||
CELL_W,
|
||
CELL_H,
|
||
READABLE_CHARS_PER_IMAGE,
|
||
DENSE_CONTENT_CHARS_PER_IMAGE,
|
||
DENSE_CONTENT_COLS,
|
||
DENSE_RENDER_STYLE,
|
||
ANTHROPIC_SLAB_COLS,
|
||
renderTextToPngsWithCharLimit,
|
||
} from './render.js';
|
||
import { factSheetText } from './factsheet.js';
|
||
import { stripSchemaDescriptions, schemaHasStructure } from './schema-strip.js';
|
||
import { bytesToBase64 } from './png.js';
|
||
import { collapseHistory, HISTORY_SYNTHETIC_INTRO } from './history.js';
|
||
import type { GptHistoryOptions } from './openai-history.js';
|
||
import { CACHE_CREATE_RATE, CACHE_READ_RATE } from './baseline.js';
|
||
|
||
/** Per-block descriptor passed to `TransformOptions.keepSharp`. */
|
||
export interface KeepSharpBlock {
|
||
/** Which live-region path is asking: `reminder`, `tool_result`, or `tool_result_part`. */
|
||
readonly kind: 'reminder' | 'tool_result' | 'tool_result_part';
|
||
/** The block's text exactly as the caller produced it (pre-render, pre-compaction). */
|
||
readonly text: string;
|
||
/** `tool_use_id` of the owning tool_result, when applicable. */
|
||
readonly toolUseId?: string;
|
||
}
|
||
|
||
/** A block pxpipe rendered to image(s), returned in `TransformInfo.recoverable`
|
||
* when the caller sets `emitRecoverable`. Lets a stateful harness restore
|
||
* byte-exact content if the model needs the imaged region verbatim. */
|
||
export interface RecoverableBlock {
|
||
/** `rec_` + 8 hex SHA-256 over kind + toolUseId + original text. */
|
||
readonly id: string;
|
||
readonly kind: 'reminder' | 'tool_result' | 'tool_result_part';
|
||
readonly toolUseId?: string;
|
||
/** Original text before compaction/reflow/paging — the bytes to restore. */
|
||
readonly text: string;
|
||
readonly imageCount: number;
|
||
}
|
||
|
||
export interface TransformOptions {
|
||
/** Master switch — false makes this a no-op pass-through. */
|
||
compress?: boolean;
|
||
/** Move tool descriptions into the same image (and stub the originals). */
|
||
compressTools?: boolean;
|
||
/** Compress large `<system-reminder>` text blocks in the first user message. */
|
||
compressReminders?: boolean;
|
||
/** Compress large tool_result text content across all user messages. */
|
||
compressToolResults?: boolean;
|
||
/** Don't compress if total compressible chars below this. */
|
||
minCompressChars?: number;
|
||
/** Per-block threshold for compressReminders (chars). */
|
||
minReminderChars?: number;
|
||
/** Per-block threshold for compressToolResults (chars). */
|
||
minToolResultChars?: number;
|
||
/** Soft-wrap column count. */
|
||
cols?: number;
|
||
/** Hard upper bound on images per tool_result; source text truncated with a paging
|
||
* marker above this to stay under Anthropic's 100-image/request cap. Default 10. */
|
||
maxImagesPerToolResult?: number;
|
||
/** Pack N text columns side-by-side per image. Default 1. Auto-clamped to stay
|
||
* under 2000 px wide. OCR ordering risk at N≥2: model must read col 1 top-to-bottom
|
||
* before col 2. */
|
||
multiCol?: number;
|
||
/** Chars-per-token assumption for `isCompressionProfitable()`. Default 4. */
|
||
charsPerToken?: number;
|
||
/** Multi-turn amortization horizon for the history-collapse gate. N≥2 evaluates as
|
||
* if N future turns share the prefix (worst-case-warm-image vs best-case-warm-text).
|
||
* Default 1 (per-turn cold gate). See docs/HISTORY_CACHE_MODEL.md. */
|
||
historyAmortizationHorizon?: number;
|
||
/** Tokens the un-rewritten path would have cache-hit on. Adds a one-time burn
|
||
* penalty `priorWarmTokens × (CC − CR)` to the image side so the gate accounts
|
||
* for invalidating a warm text cache. Default 0 (cold-start). ≤0 clamped to 0. */
|
||
priorWarmTokens?: number;
|
||
/** Symmetric counterpart: tokens the image path would have cache-hit on. Adds the
|
||
* same burn formula to the TEXT side, preventing the gate from flipping out of
|
||
* image mode when the image prefix is already warm. Default 0. ≤0 clamped to 0. */
|
||
priorWarmImageTokens?: number;
|
||
/** GPT only: collapse the OLD closed-tool-call conversation prefix into history
|
||
* image(s), keeping the recent tail as text. Independent of the static slab.
|
||
* Default on. See src/core/openai-history.ts. */
|
||
collapseHistory?: boolean;
|
||
/** GPT only: history-collapse tuning overrides (keepTail / collapseChunk / …). */
|
||
gptHistory?: Partial<GptHistoryOptions>;
|
||
/** Re-pack image-bound text into a ↵-delimited stream to fill `cols` (~29%→75-80%
|
||
* glyph-fill). ON by default (98.95% char accuracy at L1 OCR eval, +1pp vs baseline).
|
||
* Hard newlines become visible ↵ glyphs — tell the model via system prompt. */
|
||
reflow?: boolean;
|
||
/** Caller fidelity hint: return `true` for a block that must stay as text (IDs,
|
||
* hashes, file paths — content where mis-OCR would be silent and wrong). Only
|
||
* consulted on per-block live-region paths (reminders, tool_results). A throwing
|
||
* or non-boolean return is treated as `false`. */
|
||
keepSharp?: (block: KeepSharpBlock) => boolean;
|
||
/** When true, populate `TransformInfo.recoverable` with original text + provenance
|
||
* for every block rendered to images. Off by default (entries inflate `info`;
|
||
* only a stateful harness can use them). */
|
||
emitRecoverable?: boolean;
|
||
}
|
||
|
||
const DEFAULTS: Required<TransformOptions> = {
|
||
compress: true,
|
||
compressTools: true,
|
||
compressReminders: true,
|
||
compressToolResults: true,
|
||
minCompressChars: 2000,
|
||
// Below ~6k chars, per-image cost dominates savings (break-even territory).
|
||
minReminderChars: 6000,
|
||
minToolResultChars: 6000,
|
||
// system field rejects images (400 system.N.type: Input should be 'text') —
|
||
// images always go into the first user message.
|
||
// 312 cols × 5 px + 8 px pad = 1568 px (Anthropic no-resize edge).
|
||
cols: ANTHROPIC_SLAB_COLS,
|
||
maxImagesPerToolResult: 10,
|
||
charsPerToken: 4,
|
||
historyAmortizationHorizon: 1,
|
||
priorWarmTokens: 0,
|
||
priorWarmImageTokens: 0,
|
||
// Multi-col off: single-col slab already holds ~50k chars; extra OCR risk not worth it.
|
||
multiCol: 1,
|
||
reflow: true,
|
||
keepSharp: () => false,
|
||
emitRecoverable: false,
|
||
// GPT-only knobs; the Anthropic transform ignores them but Required<> needs them.
|
||
collapseHistory: true,
|
||
gptHistory: {},
|
||
};
|
||
|
||
// --- per-block break-even check ---
|
||
//
|
||
// Image token cost is computed from pixel area (Anthropic formula: w×h/750,
|
||
// empirically accurate to ~5% on dense PNGs). Constants bias CONSERVATIVE:
|
||
// CHARS_PER_TOKEN=4 under-estimates text savings; multi-col cost is linearly
|
||
// scaled from single-col + 10% margin. Mispredictions leave money on the
|
||
// table; they never generate net-loss images.
|
||
|
||
/** English ~4 chars per token average (conservative for code/JSON content). */
|
||
const CHARS_PER_TOKEN = 4;
|
||
|
||
/** Empirical cpt for the system-slab path (Opus 4.7 tokenizer, N=391, observed 1.91).
|
||
* Slab-specific because reminders/tool_results have unknown shape; those stay at 4. */
|
||
export const SLAB_CHARS_PER_TOKEN = 2.0;
|
||
|
||
// Tools whose stub description keeps a live-text read-before-edit precondition
|
||
// when full docs move into the imaged Tool Reference (read-gate audit, 2026-07-03).
|
||
const READ_FIRST_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit']);
|
||
|
||
/** Empirical cpt for the history-collapse path (same Opus 4.7 telemetry as SLAB_CHARS_PER_TOKEN).
|
||
* History is even denser (tool_use JSON dominates), so 2.0 is doubly conservative. */
|
||
export const HISTORY_CHARS_PER_TOKEN = 2.0;
|
||
|
||
/** Chars-per-token for the `pxpipe export` *reporting* estimate (factsheet & savings %).
|
||
* Less conservative than the gate's CHARS_PER_TOKEN=4: reporting wants an accurate
|
||
* figure (~3.7 for source/prose text), not a safe-side under-estimate. Single source
|
||
* of truth — src/core/export.ts imports this rather than redefining it. */
|
||
export const REPORT_CHARS_PER_TOKEN = 3.7;
|
||
|
||
/** Anthropic image-billing formula: `tokens ≈ width × height / 750`.
|
||
* https://docs.anthropic.com/en/docs/build-with-claude/vision#image-tokens
|
||
* Accurate to ~5% on dense glyph PNGs (N=14 empirical calibration). The renderer
|
||
* sizes height to content, so per-block images cost far less than full-canvas.
|
||
* Exported so the export pipeline can reuse the same constant rather than hardcoding. */
|
||
export const ANTHROPIC_PIXELS_PER_TOKEN = 750;
|
||
/** Conservative 10% upward bias on Anthropic image token estimates — keeps the gate
|
||
* on the safe (pass-through) side when the true cost is near the break-even point.
|
||
* Exported so the export pipeline reuses the same value. */
|
||
export const IMAGE_COST_SAFETY_MARGIN = 1.10;
|
||
|
||
/** Width in px of a single-col PNG. Must stay in sync with `renderChunkToPng` (render.ts). */
|
||
function singleColWidthPx(cols: number): number {
|
||
return 2 * PAD_X + cols * CELL_W;
|
||
}
|
||
|
||
/** Width in px of a multi-col PNG. Mirrors `multiColWidth()` in render.ts. */
|
||
function multiColWidthPx(cols: number, numCols: number): number {
|
||
const n = Math.max(1, numCols | 0);
|
||
if (n === 1) return singleColWidthPx(cols);
|
||
const GUTTER_CELLS = 4; // must match render.ts (not exported)
|
||
return 2 * PAD_X + n * cols * CELL_W + (n - 1) * GUTTER_CELLS * CELL_W;
|
||
}
|
||
|
||
/** Exact image-token cost for `visualRows` at given column/multi-col geometry.
|
||
* Mirrors the renderer's height math so the gate matches Anthropic billing.
|
||
* Last image is partial-height; each image cost ∝ pixel area. */
|
||
function imageTokensForRows(
|
||
visualRows: number,
|
||
cols: number,
|
||
numCols: number = 1,
|
||
imageCountCap?: number,
|
||
maxCharsPerImage: number = READABLE_CHARS_PER_IMAGE,
|
||
): number {
|
||
if (!Number.isFinite(visualRows) || visualRows <= 0) return 0;
|
||
const n = Math.max(1, numCols | 0);
|
||
const widthPx = multiColWidthPx(cols, n);
|
||
const hardLinesPerImg = Math.max(1, Math.floor((MAX_HEIGHT_PX - 2 * PAD_Y) / CELL_H));
|
||
const readableLinesPerCol = Math.max(1, Math.floor(maxCharsPerImage / Math.max(1, cols)));
|
||
const linesPerImg = Math.min(hardLinesPerImg, readableLinesPerCol);
|
||
const rowsPerImage = linesPerImg; // pixel rows per image (height)
|
||
const linesPerImage = linesPerImg * n; // wrapped-text lines per image (n cols side-by-side)
|
||
let imagesNeeded = Math.ceil(visualRows / linesPerImage);
|
||
if (imageCountCap !== undefined && imageCountCap > 0) {
|
||
imagesNeeded = Math.min(imagesNeeded, imageCountCap);
|
||
}
|
||
const fullImages = Math.max(0, imagesNeeded - 1);
|
||
const linesInLast = visualRows - fullImages * linesPerImage;
|
||
// Column-major layout: pixel rows = min(linesInLast, rowsPerImage).
|
||
const rowsInLast = Math.min(Math.max(1, linesInLast), rowsPerImage);
|
||
const fullImageHeight = 2 * PAD_Y + rowsPerImage * CELL_H;
|
||
const lastImageHeight = 2 * PAD_Y + rowsInLast * CELL_H;
|
||
const totalPixels = fullImages * widthPx * fullImageHeight + widthPx * lastImageHeight;
|
||
return Math.ceil((totalPixels / ANTHROPIC_PIXELS_PER_TOKEN) * IMAGE_COST_SAFETY_MARGIN);
|
||
}
|
||
|
||
/** Exact image-token cost for `text`. Uses `countVisualRows` and optionally
|
||
* `shrinkColsToContent` (default true) so narrow blocks aren't priced at full
|
||
* canvas width. Pass `shrinkWidth=false` for the system slab (fills full `cols`). */
|
||
function imageTokensCost(
|
||
text: string,
|
||
cols: number,
|
||
numCols: number = 1,
|
||
imageCountCap?: number,
|
||
shrinkWidth: boolean = true,
|
||
maxCharsPerImage: number = READABLE_CHARS_PER_IMAGE,
|
||
): number {
|
||
const effectiveCols = shrinkWidth ? shrinkColsToContent(text, cols) : cols;
|
||
const rows = countVisualRows(text, effectiveCols);
|
||
return imageTokensForRows(rows, effectiveCols, numCols, imageCountCap, maxCharsPerImage);
|
||
}
|
||
|
||
/** Gate geometry for the single-col dense path (tool_result, reminder, history).
|
||
* Dense single-col uses DENSE_CONTENT_COLS/DENSE_CONTENT_CHARS_PER_IMAGE;
|
||
* multi-col uses configured `cols` at READABLE budget. Slab uses its own path. */
|
||
function denseGateGeometry(cols: number, numCols: number): { cols: number; maxChars: number } {
|
||
return Math.max(1, numCols | 0) > 1
|
||
? { cols, maxChars: READABLE_CHARS_PER_IMAGE }
|
||
: { cols: DENSE_CONTENT_COLS, maxChars: DENSE_CONTENT_CHARS_PER_IMAGE };
|
||
}
|
||
|
||
/** Visual rows per image: `floor((MAX_HEIGHT_PX − 2·PAD_Y) / CELL_H)`. Derived
|
||
* from render.ts constants so break-even math auto-tracks cell geometry changes. */
|
||
export const LINES_PER_IMAGE = Math.max(1, Math.floor((MAX_HEIGHT_PX - 2 * PAD_Y) / CELL_H));
|
||
|
||
export function maxCharsPerImage(cols: number): number {
|
||
return Math.min(cols * LINES_PER_IMAGE, READABLE_CHARS_PER_IMAGE);
|
||
}
|
||
|
||
/** Lossless pre-render whitespace compactor (each `\n` costs ≥1 visual row):
|
||
* 1. Strip trailing whitespace per line (preserves leading indent).
|
||
* 2. Collapse 3+ consecutive newlines to 2. Typically saves 10-25% rows on
|
||
* markdown/tool-doc slabs, enough to flip borderline gates to profitable. */
|
||
export function compactSlabWhitespace(text: string): string {
|
||
if (!text) return text;
|
||
// Single-pass trailing whitespace strip (avoids materializing a split array on ~160 KB slabs).
|
||
let trimmed = '';
|
||
let lineStart = 0;
|
||
for (let i = 0; i <= text.length; i++) {
|
||
if (i === text.length || text.charCodeAt(i) === 10 /* \n */) {
|
||
let end = i;
|
||
while (end > lineStart) {
|
||
const c = text.charCodeAt(end - 1);
|
||
if (c !== 32 && c !== 9) break;
|
||
end--;
|
||
}
|
||
trimmed += text.slice(lineStart, end);
|
||
if (i < text.length) trimmed += '\n';
|
||
lineStart = i + 1;
|
||
}
|
||
}
|
||
// Collapse 3+ newlines → 2 (kills multi-blank dividers; each costs a render row).
|
||
return trimmed.replace(/\n{3,}/g, '\n\n');
|
||
}
|
||
|
||
/** Apply R3 reflow when enabled. Run after `compactSlabWhitespace`, before
|
||
* the gate (gate/renderer/paging all see the same dense text). Falls back to
|
||
* input unchanged on sentinel collision. */
|
||
function maybeReflow(text: string, enabled: boolean): string {
|
||
if (!enabled) return text;
|
||
// Neutralize any pre-existing ↵ so reflow packs newlines instead of bailing to a raw,
|
||
// unpacked render (the tool_result "newlines not converted to ↵" case — common when the
|
||
// content is about pxpipe itself). Render-only; originals are preserved via
|
||
// recordRecoverable(innerRaw), so this substitution never reaches recovery.
|
||
const safe = neutralizeSentinel(text);
|
||
return reflow(safe) ?? safe;
|
||
}
|
||
|
||
/** Decompose the break-even gate into components for telemetry. Returns the
|
||
* imageTokens, textTokens, and symmetric burn terms the gate uses internally,
|
||
* or `null` for empty/non-finite input. */
|
||
export function evalCompressionProfitability(
|
||
text: string,
|
||
cols: number,
|
||
imageCountCap: number | undefined = undefined,
|
||
numCols: number = 1,
|
||
charsPerToken: number = CHARS_PER_TOKEN,
|
||
priorWarmTokens: number = 0,
|
||
priorWarmImageTokens: number = 0,
|
||
shrinkWidth: boolean = true,
|
||
): {
|
||
imageTokens: number;
|
||
textTokens: number;
|
||
burnImageSide: number;
|
||
burnTextSide: number;
|
||
profitable: boolean;
|
||
} | null {
|
||
const n = Math.max(1, numCols | 0);
|
||
if (typeof text !== 'string' || text.length === 0) return null;
|
||
const cpt = Number.isFinite(charsPerToken) && charsPerToken > 0
|
||
? charsPerToken
|
||
: CHARS_PER_TOKEN;
|
||
const imageTokens = imageTokensCost(text, cols, n, imageCountCap, shrinkWidth);
|
||
const textTokens = text.length / cpt;
|
||
const burnImageSide = Number.isFinite(priorWarmTokens) && priorWarmTokens > 0
|
||
? priorWarmTokens * (CACHE_CREATE_RATE - CACHE_READ_RATE)
|
||
: 0;
|
||
const burnTextSide = Number.isFinite(priorWarmImageTokens) && priorWarmImageTokens > 0
|
||
? priorWarmImageTokens * (CACHE_CREATE_RATE - CACHE_READ_RATE)
|
||
: 0;
|
||
return {
|
||
imageTokens,
|
||
textTokens,
|
||
burnImageSide,
|
||
burnTextSide,
|
||
profitable: imageTokens + burnImageSide < textTokens + burnTextSide,
|
||
};
|
||
}
|
||
|
||
export function isCompressionProfitable(
|
||
text: string,
|
||
cols: number = DEFAULTS.cols,
|
||
imageCountCap?: number,
|
||
numCols: number = 1,
|
||
charsPerToken: number = CHARS_PER_TOKEN,
|
||
priorWarmTokens: number = 0,
|
||
priorWarmImageTokens: number = 0,
|
||
shrinkWidth: boolean = true,
|
||
maxCharsPerImage: number = READABLE_CHARS_PER_IMAGE,
|
||
): boolean {
|
||
const n = Math.max(1, numCols | 0);
|
||
if (typeof text !== 'string' || text.length === 0) return false;
|
||
const cpt = Number.isFinite(charsPerToken) && charsPerToken > 0
|
||
? charsPerToken
|
||
: CHARS_PER_TOKEN;
|
||
const imageTokensCost_ = imageTokensCost(text, cols, n, imageCountCap, shrinkWidth, maxCharsPerImage);
|
||
const textTokensEquivalent = text.length / cpt;
|
||
// Symmetric burn penalty (anti-flapping): switching modes invalidates the warm
|
||
// cache on whichever side was warm, paying cache_create. Burn is added to the
|
||
// side that would flip — pinning the session in its current mode until
|
||
// per-turn savings exceed the burn cost.
|
||
const burnImageSide = Number.isFinite(priorWarmTokens) && priorWarmTokens > 0
|
||
? priorWarmTokens * (CACHE_CREATE_RATE - CACHE_READ_RATE)
|
||
: 0;
|
||
const burnTextSide = Number.isFinite(priorWarmImageTokens) && priorWarmImageTokens > 0
|
||
? priorWarmImageTokens * (CACHE_CREATE_RATE - CACHE_READ_RATE)
|
||
: 0;
|
||
return imageTokensCost_ + burnImageSide < textTokensEquivalent + burnTextSide;
|
||
}
|
||
|
||
/**
|
||
* Horizon-aware variant of `isCompressionProfitable` for history-collapse.
|
||
*
|
||
* Evaluates expected lifetime cost over N turns: worst-case-warm for image
|
||
* (cache_create turn 1, cache_read turns 2..N) vs best-case-warm for text
|
||
* (cache_read all N). Gate condition: I×(CC + CR×(N-1)) < T×CR×N.
|
||
* Examples: N=5 → I < 0.30×T; N=10 → I < 0.47×T.
|
||
* Falls back to cold per-turn gate when `horizon <= 1`. See docs/HISTORY_CACHE_MODEL.md.
|
||
*/
|
||
export function isCompressionProfitableAmortized(
|
||
text: string,
|
||
cols: number,
|
||
imageCountCap: number | undefined,
|
||
numCols: number,
|
||
charsPerToken: number,
|
||
horizon: number,
|
||
priorWarmTokens: number = 0,
|
||
priorWarmImageTokens: number = 0,
|
||
shrinkWidth: boolean = true,
|
||
maxCharsPerImage: number = READABLE_CHARS_PER_IMAGE,
|
||
): boolean {
|
||
if (!Number.isFinite(horizon) || horizon <= 1) {
|
||
return isCompressionProfitable(text, cols, imageCountCap, numCols, charsPerToken, priorWarmTokens, priorWarmImageTokens, shrinkWidth, maxCharsPerImage);
|
||
}
|
||
const N = Math.max(2, Math.floor(horizon));
|
||
const n = Math.max(1, numCols | 0);
|
||
if (typeof text !== 'string' || text.length === 0) return false;
|
||
const cpt = Number.isFinite(charsPerToken) && charsPerToken > 0
|
||
? charsPerToken
|
||
: CHARS_PER_TOKEN;
|
||
const imageTokens = imageTokensCost(text, cols, n, imageCountCap, shrinkWidth, maxCharsPerImage);
|
||
const textTokens = text.length / cpt;
|
||
// Worst-case-for-image vs best-case-for-text (conservative, on purpose).
|
||
const imageLifetime = imageTokens * (CACHE_CREATE_RATE + CACHE_READ_RATE * (N - 1));
|
||
const textLifetime = textTokens * CACHE_READ_RATE * N;
|
||
// Symmetric burn — see isCompressionProfitable for anti-flapping rationale.
|
||
const burnImageSide = Number.isFinite(priorWarmTokens) && priorWarmTokens > 0
|
||
? priorWarmTokens * (CACHE_CREATE_RATE - CACHE_READ_RATE)
|
||
: 0;
|
||
const burnTextSide = Number.isFinite(priorWarmImageTokens) && priorWarmImageTokens > 0
|
||
? priorWarmImageTokens * (CACHE_CREATE_RATE - CACHE_READ_RATE)
|
||
: 0;
|
||
return imageLifetime + burnImageSide < textLifetime + burnTextSide;
|
||
}
|
||
|
||
|
||
/** Increment a passthrough-reason counter on `info`. Lazily allocates `passthroughReasons`. */
|
||
function bumpPassthrough(
|
||
info: TransformInfo,
|
||
reason: 'below_threshold' | 'not_profitable' | 'kept_sharp',
|
||
): void {
|
||
if (!info.passthroughReasons) info.passthroughReasons = {};
|
||
info.passthroughReasons[reason] = (info.passthroughReasons[reason] ?? 0) + 1;
|
||
}
|
||
|
||
/** Invoke `keepSharp` defensively; a throw or non-`true` return means "image as usual". */
|
||
function callerKeepsSharp(
|
||
fn: ((block: KeepSharpBlock) => boolean) | undefined,
|
||
block: KeepSharpBlock,
|
||
): boolean {
|
||
if (typeof fn !== 'function') return false;
|
||
try {
|
||
return fn(block) === true;
|
||
} catch {
|
||
return false;
|
||
}
|
||
}
|
||
|
||
/** Logical bucket for per-gate-call char attribution. Used by the rolling-cpt
|
||
* regression to derive per-bucket marginal cpt from production telemetry. */
|
||
export type BucketName =
|
||
| 'static_slab'
|
||
| 'reminder'
|
||
| 'tool_result_json'
|
||
| 'tool_result_log'
|
||
| 'tool_result_prose'
|
||
| 'history';
|
||
|
||
/** Pre-compaction TEXT char totals per bucket. Absent when no bucket fired. */
|
||
export type BucketChars = Partial<Record<BucketName, number>>;
|
||
|
||
/** Attribute `chars` to a compression bucket (called whether gate accepted or rejected). */
|
||
function bumpBucket(info: TransformInfo, bucket: BucketName, chars: number): void {
|
||
if (chars <= 0) return;
|
||
if (!info.bucketChars) info.bucketChars = {};
|
||
info.bucketChars[bucket] = (info.bucketChars[bucket] ?? 0) + chars;
|
||
}
|
||
|
||
/** Map `classifyContent` shape to a tool_result bucket name. */
|
||
function toolResultBucket(shape: 'structured' | 'log' | 'other'): BucketName {
|
||
if (shape === 'structured') return 'tool_result_json';
|
||
if (shape === 'log') return 'tool_result_log';
|
||
return 'tool_result_prose';
|
||
}
|
||
|
||
/** Parsed contents of Claude Code's <env> + git status blocks. All optional —
|
||
* fields are only populated if the corresponding line is present. */
|
||
export interface EnvFields {
|
||
/** Working directory at the time `claude` was launched. */
|
||
cwd?: string;
|
||
isGitRepo?: boolean;
|
||
/** Current git branch, parsed from <git_status> or a "Branch:" line. */
|
||
gitBranch?: string;
|
||
platform?: string;
|
||
osVersion?: string;
|
||
/** "Today's date" as Claude Code reported it (YYYY-MM-DD). */
|
||
today?: string;
|
||
}
|
||
|
||
export interface TransformInfo {
|
||
compressed: boolean;
|
||
reason?: string;
|
||
origChars: number;
|
||
/** Total source chars image-encoded this request (static slab + reminders + tool_results).
|
||
* Unlike `origChars` (static slab + tool docs only), reflects what `imageCount` replaced. */
|
||
compressedChars: number;
|
||
imageCount: number;
|
||
imageBytes: number;
|
||
/** Σ width×height across all rendered images. Pairs with upstream token count for
|
||
* empirical px/token regression: `tokens ≈ α·outgoingTextChars + β·imagePixels`. */
|
||
imagePixels?: number;
|
||
/** GPT only. Vision tokens the rendered images actually cost as input
|
||
* (Σ openAIVisionTokens over real image dims). The "Sent as image" basis. */
|
||
imageTokens?: number;
|
||
/** GPT only. o200k_base text tokens of the content pxpipe imaged/stripped —
|
||
* the would-have-paid "as plain text" baseline. Compared against imageTokens
|
||
* for the per-request saving. See src/core/openai-savings.ts. */
|
||
baselineImagedTokens?: number;
|
||
/** Total TEXT chars in the outgoing body (system + messages, excluding image base64).
|
||
* Denominator for empirical chars-per-token regression on cold-miss events. */
|
||
outgoingTextChars?: number;
|
||
/** Length of the static (cacheable) slab rendered into the image. */
|
||
staticChars: number;
|
||
/** Length of the dynamic (per-turn) slab kept as plain text. */
|
||
dynamicChars: number;
|
||
/** Chars of volatile env/context text relocated from system to the tail of
|
||
* the last user message (absent when kept in system fallback). */
|
||
envRelocatedChars?: number;
|
||
dynamicBlockCount: number;
|
||
/** Tag-shaped blocks in the static slab not in DYNAMIC_BLOCK_TAGS.
|
||
* Canary: a new per-turn Claude Code tag would appear here before cache rate collapses. */
|
||
unknownStaticTags?: string[];
|
||
/** Static-slab tags whose content changed within a session — proven dynamic,
|
||
* busting the image cache each turn. The real alert signal. */
|
||
churningStaticTags?: string[];
|
||
env?: EnvFields;
|
||
/** sha8 of static slab + tool docs (what goes in the image). Repeats across turns → cache hits. */
|
||
systemSha8?: string;
|
||
/** sha8 of the CLAUDE.md section, for bucketing by project when cwd is absent. */
|
||
claudeMdSha8?: string;
|
||
/** sha8 of first user message text (first 4 KiB). Rough thread/session id. */
|
||
firstUserSha8?: string;
|
||
/** Raw bytes of the first rendered image. Dashboard preview only; NOT persisted to JSONL. */
|
||
firstImagePng?: Uint8Array;
|
||
firstImageWidth?: number;
|
||
firstImageHeight?: number;
|
||
/** All rendered PNGs this request. Dashboard only; NOT persisted to JSONL. */
|
||
imagePngs?: Uint8Array[];
|
||
imageDims?: Array<{ width: number; height: number }>;
|
||
/** Source text rendered to images (slab + header), capped at 64 KiB. NOT persisted. */
|
||
imageSourceText?: string;
|
||
reminderImgs?: number;
|
||
toolResultImgs?: number;
|
||
/** Chars of tool docs moved to the system-text Tool Reference (not imaged). */
|
||
toolDocsChars?: number;
|
||
/** Codepoints missing from the atlas (rendered as blank cells). Telemetry for atlas tuning. */
|
||
droppedChars?: number;
|
||
/** Top dropped codepoints by frequency (`U+HHHH` → count), at most 20 entries. */
|
||
droppedCodepointsTop?: Record<string, number>;
|
||
/** Why blocks passed through without compression. Only present when count > 0. */
|
||
passthroughReasons?: { below_threshold?: number; not_profitable?: number; kept_sharp?: number };
|
||
/** Slab gate diagnostics — imageTokens, textTokens, burn terms, and verdict.
|
||
* Lets hosts measure flap-prevention efficacy and tune amortization horizon. */
|
||
gateEval?: {
|
||
readonly site: 'slab';
|
||
readonly imageTokens: number;
|
||
readonly textTokens: number;
|
||
/** `priorWarmTokens × (CC − CR)` added to image side. */
|
||
readonly burnImageSide: number;
|
||
/** `priorWarmImageTokens × (CC − CR)` added to text side (anti-flapping anchor). */
|
||
readonly burnTextSide: number;
|
||
readonly profitable: boolean;
|
||
};
|
||
/** Pre-compaction TEXT char totals per gate-call bucket. Rolling-cpt regression denominator. */
|
||
bucketChars?: BucketChars;
|
||
/** Chars fed into the history-image renderer. Folded into `bucketChars.history` too. */
|
||
historyTextChars?: number;
|
||
/** Blocks pinned as text by the caller's `keepSharp` predicate this request. */
|
||
keptSharpBlocks?: number;
|
||
/** Imaged live-region blocks with original text + provenance, when `emitRecoverable`. */
|
||
recoverable?: RecoverableBlock[];
|
||
truncatedToolResults?: number;
|
||
omittedChars?: number;
|
||
/** History-collapse: messages collapsed into the synthetic prepended user message. */
|
||
collapsedTurns?: number;
|
||
collapsedChars?: number;
|
||
/** History-collapse images. Also folded into `info.imageCount`. */
|
||
collapsedImages?: number;
|
||
/** sha8 of concatenated history-image base64. Stable across the collapse window →
|
||
* proves Anthropic's prompt cache can `cache_read` (0.1×) instead of `cache_create`.
|
||
* A changing hash means cache-key drift is back. Only set when collapse produced images. */
|
||
historyImageSha?: string;
|
||
/** sha8 of the ACTUAL cacheable prefix sent this turn (tools + system +
|
||
* message blocks through the imaged history/slab boundary; the live tail is
|
||
* excluded). Read-only measurement. A change turn-over-turn within a session
|
||
* ⇒ pxpipe serialized different prefix bytes (we busted our own cache,
|
||
* pxpipe-side); STABLE while cache_create spikes / cache_read collapses ⇒ the
|
||
* prefix was evicted upstream. Decisive attribution signal (see #11). */
|
||
cachePrefixSha8?: string;
|
||
/** Approx size (chars) of that cached prefix — pairs with cachePrefixSha8 so a
|
||
* bust reads as growth (size up) vs pure invalidation (size unchanged). */
|
||
cachePrefixBytes?: number;
|
||
/** Why the history collapse didn't run (or did). Diagnostic only. */
|
||
historyReason?:
|
||
| 'no_history'
|
||
| 'prefix_too_short'
|
||
| 'no_closed_prefix'
|
||
| 'below_min_chars'
|
||
| 'below_min_tokens'
|
||
| 'not_profitable'
|
||
| 'too_many_images'
|
||
| 'render_empty'
|
||
| 'collapsed';
|
||
/** Token count of the pre-compression body from /v1/messages/count_tokens (free).
|
||
* Absent when probe failed — event excluded from savings rollup. */
|
||
baselineTokens?: number;
|
||
/** Token count of the pre-compression body truncated at the last cache_control marker.
|
||
* Absent when the original body has no cache_control markers (cacheable=0 exactly). */
|
||
baselineCacheableTokens?: number;
|
||
/** 'ok': both probes resolved. 'partial': full-body resolved but cacheable-prefix
|
||
* didn't (exclude from rollup — cacheable=0 fallback is dishonest). 'failed': no
|
||
* baseline. undefined: no probe attempted. */
|
||
baselineProbeStatus?: 'ok' | 'partial' | 'failed';
|
||
}
|
||
|
||
// --- helpers ---------------------------------------------------------------
|
||
|
||
/** Extract (text, remainder) from a system field that may be string or block list. */
|
||
function extractSystemText(sys: SystemField | undefined): { text: string; kept: SystemField } {
|
||
if (sys == null) return { text: '', kept: [] };
|
||
if (typeof sys === 'string') return { text: sys, kept: '' };
|
||
const textParts: string[] = [];
|
||
const kept: SystemField = [];
|
||
for (const block of sys) {
|
||
if (block && typeof block === 'object' && block.type === 'text') {
|
||
textParts.push(block.text);
|
||
} else {
|
||
kept.push(block);
|
||
}
|
||
}
|
||
return { text: textParts.join('\n\n'), kept };
|
||
}
|
||
|
||
function lastStaticSystemCacheControl(sys: SystemField | undefined): TextBlock['cache_control'] | undefined {
|
||
if (!Array.isArray(sys)) return undefined;
|
||
let cacheControl: TextBlock['cache_control'] | undefined;
|
||
for (const block of sys) {
|
||
if (!block || block.type !== 'text' || block.cache_control === undefined) continue;
|
||
const { body } = stripBillingLine(block.text);
|
||
if (splitStaticDynamic(body).staticText.length > 0) {
|
||
cacheControl = block.cache_control;
|
||
}
|
||
}
|
||
return cacheControl;
|
||
}
|
||
|
||
// Per-turn dynamic blocks injected by Claude Code. These drift turn-to-turn and
|
||
// must not be baked into the cached image. Split out so only the stable static
|
||
// slab (CLAUDE.md + tool docs) carries cache_control.
|
||
const DYNAMIC_BLOCK_TAGS = [
|
||
'env',
|
||
'context',
|
||
'git_status',
|
||
'directoryStructure',
|
||
'system-reminder',
|
||
] as const;
|
||
|
||
// Known-static slab tags — suppresses first-sighting `unknownStaticTags` noise
|
||
// only. Correctness doesn't depend on this list: observeStaticTagChurn catches
|
||
// a wrong entry on its second sighting.
|
||
const KNOWN_STATIC_TAGS = [
|
||
// Claude Code
|
||
'types',
|
||
// opencode (codex system prompts have no tag-shaped blocks)
|
||
'example',
|
||
'available_skills',
|
||
// beast.txt + title.txt
|
||
'examples',
|
||
'rules',
|
||
'task',
|
||
// copilot-gpt-5.txt
|
||
'codeSearchInstructions',
|
||
'codeSearchToolUseInstructions',
|
||
'communicationGuidelines',
|
||
'gptAgentInstructions',
|
||
'outputFormatting',
|
||
'structuredWorkflow',
|
||
'toolUseInstructions',
|
||
] as const;
|
||
|
||
function splitStaticDynamic(text: string): {
|
||
staticText: string;
|
||
dynamicText: string;
|
||
blockCount: number;
|
||
unknownTags: string[];
|
||
/** tag → concatenated inner content of same-named slab blocks. */
|
||
staticTagContents: Map<string, string>;
|
||
} {
|
||
if (!text)
|
||
return {
|
||
staticText: '',
|
||
dynamicText: '',
|
||
blockCount: 0,
|
||
unknownTags: [],
|
||
staticTagContents: new Map(),
|
||
};
|
||
const pattern = new RegExp(
|
||
`<(${DYNAMIC_BLOCK_TAGS.join('|')})(\\s[^>]*)?>[\\s\\S]*?</\\1>`,
|
||
'g',
|
||
);
|
||
const dynamicParts: string[] = [];
|
||
let staticBuf = '';
|
||
let cursor = 0;
|
||
let m: RegExpExecArray | null;
|
||
while ((m = pattern.exec(text)) !== null) {
|
||
staticBuf += text.slice(cursor, m.index);
|
||
dynamicParts.push(m[0]);
|
||
cursor = m.index + m[0].length;
|
||
}
|
||
staticBuf += text.slice(cursor);
|
||
|
||
// Sniff for unknown tag-shaped blocks in the static slab. A new per-turn
|
||
// Claude Code tag would silently bake into the image and collapse cache rate;
|
||
// surfacing the tag name lets us detect it within hours of a release.
|
||
const known = new Set<string>(DYNAMIC_BLOCK_TAGS);
|
||
const knownStatic = new Set<string>(KNOWN_STATIC_TAGS);
|
||
const sniffer = /<([a-zA-Z][a-zA-Z0-9_-]*)(?:\s[^>]*)?>([\s\S]*?)<\/\1>/g;
|
||
const unknown = new Set<string>();
|
||
const staticTagContents = new Map<string, string>();
|
||
let s: RegExpExecArray | null;
|
||
while ((s = sniffer.exec(staticBuf)) !== null) {
|
||
const tag = s[1]!;
|
||
if (tag.length > 64) continue;
|
||
if (!known.has(tag) && !knownStatic.has(tag)) unknown.add(tag);
|
||
// Fold repeated tags (e.g. several <example>s) into one fingerprint.
|
||
staticTagContents.set(tag, (staticTagContents.get(tag) ?? '') + s[2]!);
|
||
}
|
||
|
||
return {
|
||
// Collapse the run of blank lines left behind by removed blocks.
|
||
staticText: staticBuf.replace(/\n{3,}/g, '\n\n').trim(),
|
||
dynamicText: dynamicParts.join('\n\n'),
|
||
blockCount: dynamicParts.length,
|
||
unknownTags: [...unknown],
|
||
staticTagContents,
|
||
};
|
||
}
|
||
|
||
/** FNV-1a 32-bit — cheap synchronous content fingerprint for churn detection. */
|
||
function fnv1a(text: string): number {
|
||
let h = 0x811c9dc5;
|
||
for (let i = 0; i < text.length; i++) {
|
||
h ^= text.charCodeAt(i);
|
||
h = Math.imul(h, 0x01000193);
|
||
}
|
||
return h >>> 0;
|
||
}
|
||
|
||
// Last content hash per (session, tag). Bounded LRU.
|
||
const TAG_OBSERVATIONS_MAX = 4096;
|
||
const tagObservations = new Map<string, number>();
|
||
|
||
/** Returns slab tags whose content changed since the last sighting in the same
|
||
* session — proven per-turn dynamics, whatever the hardcoded lists say. */
|
||
function observeStaticTagChurn(
|
||
sessionKey: string,
|
||
tagContents: ReadonlyMap<string, string>,
|
||
): string[] {
|
||
const churned: string[] = [];
|
||
for (const [tag, inner] of tagContents) {
|
||
const key = `${sessionKey}\0${tag}`;
|
||
const hash = fnv1a(inner);
|
||
const prev = tagObservations.get(key);
|
||
if (prev !== undefined) {
|
||
if (prev !== hash) churned.push(tag);
|
||
tagObservations.delete(key); // refresh LRU position
|
||
}
|
||
tagObservations.set(key, hash);
|
||
}
|
||
while (tagObservations.size > TAG_OBSERVATIONS_MAX) {
|
||
const oldest = tagObservations.keys().next().value;
|
||
if (oldest === undefined) break;
|
||
tagObservations.delete(oldest);
|
||
}
|
||
return churned;
|
||
}
|
||
|
||
/** sha256[0..8] hex via Web Crypto (works in Node 18+ and Workers). 32-bit collision-safe. */
|
||
export async function sha8(text: string): Promise<string> {
|
||
const buf = new TextEncoder().encode(text);
|
||
const digest = await crypto.subtle.digest('SHA-256', buf);
|
||
const bytes = new Uint8Array(digest);
|
||
let hex = '';
|
||
for (let i = 0; i < 4; i++) hex += bytes[i]!.toString(16).padStart(2, '0');
|
||
return hex;
|
||
}
|
||
|
||
/** Record a recovery entry when `emitRecoverable` is on. No-op (no hash cost) when off. */
|
||
async function recordRecoverable(
|
||
info: TransformInfo,
|
||
emit: boolean,
|
||
entry: { kind: RecoverableBlock['kind']; toolUseId?: string; text: string; imageCount: number },
|
||
): Promise<void> {
|
||
if (!emit) return;
|
||
const id = 'rec_' + (await sha8(`${entry.kind}\u0000${entry.toolUseId ?? ''}\u0000${entry.text}`));
|
||
(info.recoverable ??= []).push({
|
||
id,
|
||
kind: entry.kind,
|
||
...(entry.toolUseId !== undefined ? { toolUseId: entry.toolUseId } : {}),
|
||
text: entry.text,
|
||
imageCount: entry.imageCount,
|
||
});
|
||
}
|
||
|
||
/** Hash the concatenated base64 of every image block on `messages[0]` (the synthetic
|
||
* history message). Stable across the quantized collapse window → proves Anthropic
|
||
* can cache_read the history prefix. Returns undefined if no images on messages[0]. */
|
||
async function historyImageSha8(
|
||
messages: Message[],
|
||
): Promise<string | undefined> {
|
||
const synthetic = messages[0];
|
||
if (!synthetic || !Array.isArray(synthetic.content)) return undefined;
|
||
let concat = '';
|
||
for (const blk of synthetic.content) {
|
||
if (blk.type === 'image') concat += blk.source.data;
|
||
}
|
||
return concat ? sha8(concat) : undefined;
|
||
}
|
||
|
||
/**
|
||
* After a history collapse, move pxpipe's single relocated cache breakpoint off
|
||
* the slab image and onto the LAST history image.
|
||
*
|
||
* The history image sits AFTER the slab in prefix order, so one marker on it
|
||
* caches the WHOLE imaged prefix (slab + history) as a single stable segment —
|
||
* created once, then read at the ~0.1x rate every turn. Without this the history
|
||
* image (usually the largest block) only lands in a cached prefix when the
|
||
* caller's roaming downstream marker happens to fall after it; when it doesn't,
|
||
* the entire history image re-creates at the 1.25x rate turn after turn.
|
||
*
|
||
* Pure relocation: it acts only when a slab image already carries the anchor, so
|
||
* the total marker count never increases (pxpipe never *adds* — only moves).
|
||
*/
|
||
function relocateAnchorToHistoryImage(messages: Message[] | undefined, anchorOrdinal?: number): void {
|
||
if (!Array.isArray(messages)) return;
|
||
|
||
// The synthetic history message is identified by its banner text block.
|
||
let historyImg: (ImageBlock & { cache_control?: unknown }) | undefined;
|
||
for (const m of messages) {
|
||
if (!Array.isArray(m.content)) continue;
|
||
const first = m.content[0] as TextBlock | undefined;
|
||
if (!first || first.type !== 'text' || first.text !== HISTORY_SYNTHETIC_INTRO) continue;
|
||
// Collect this message's images in order, then pin the carry-over anchor (the last
|
||
// byte-stable history image) when collapseHistory provided its ordinal; otherwise
|
||
// fall back to the last image. Pinning the LAST image is the #11 bust: it's the
|
||
// newest, still-growing chunk and its bytes change on every window advance.
|
||
const imgsInMsg: Array<ImageBlock & { cache_control?: unknown }> = [];
|
||
for (const b of m.content) {
|
||
if (b && (b as ImageBlock).type === 'image') {
|
||
imgsInMsg.push(b as ImageBlock & { cache_control?: unknown });
|
||
}
|
||
}
|
||
historyImg =
|
||
anchorOrdinal !== undefined && anchorOrdinal >= 0 && anchorOrdinal < imgsInMsg.length
|
||
? imgsInMsg[anchorOrdinal]
|
||
: imgsInMsg[imgsInMsg.length - 1];
|
||
break;
|
||
}
|
||
if (!historyImg) return;
|
||
|
||
// The slab anchor is the marked image BEFORE the '[End of rendered context.]'
|
||
// boundary in the slab-bearing message. Reminder/tool images sit after that
|
||
// boundary (or in other messages) and keep their own caller markers.
|
||
let slabAnchor: (ImageBlock & { cache_control?: unknown }) | undefined;
|
||
for (const m of messages) {
|
||
if (!Array.isArray(m.content)) continue;
|
||
const hasBoundary = m.content.some(
|
||
(b) => b && (b as TextBlock).type === 'text' && (b as TextBlock).text === '[End of rendered context.]',
|
||
);
|
||
if (!hasBoundary) continue;
|
||
for (const b of m.content) {
|
||
if (b && (b as TextBlock).type === 'text' && (b as TextBlock).text === '[End of rendered context.]') break;
|
||
if (b && (b as ImageBlock).type === 'image' && (b as { cache_control?: unknown }).cache_control !== undefined) {
|
||
slabAnchor = b as ImageBlock & { cache_control?: unknown };
|
||
}
|
||
}
|
||
break;
|
||
}
|
||
if (!slabAnchor) return; // nothing to relocate → never add a marker
|
||
|
||
historyImg.cache_control = slabAnchor.cache_control;
|
||
delete slabAnchor.cache_control;
|
||
}
|
||
|
||
/**
|
||
* Read-only digest of the cacheable prefix pxpipe actually sends: tools +
|
||
* system + message blocks up to and including the imaged history image (or, on
|
||
* no-collapse turns, the slab boundary). The naturally-growing live tail is
|
||
* excluded, so the digest only moves when something *inside the pinned prefix*
|
||
* moves. Pairs with per-turn cache_read/cache_create to attribute a prompt-cache
|
||
* bust: a digest that CHANGES between consecutive turns of one session means we
|
||
* serialized different prefix bytes (pxpipe-side — a per-turn block crossing the
|
||
* breakpoint, or marker drift); a STABLE digest on a turn that still re-created
|
||
* the prefix points upstream (eviction). Never mutates the request, so it cannot
|
||
* perturb the cache behavior it measures.
|
||
*/
|
||
async function cachePrefixDigest(
|
||
req: { tools?: unknown; system?: unknown; messages?: unknown },
|
||
): Promise<{ sha8: string; bytes: number } | undefined> {
|
||
const msgs = Array.isArray(req.messages) ? (req.messages as Message[]) : [];
|
||
// Boundary = latest message carrying pxpipe's imaged prefix: the history image
|
||
// (banner) when collapse ran, else the slab message ('[End of rendered
|
||
// context.]'). Identified exactly as relocateAnchorToHistoryImage does.
|
||
let boundary = -1;
|
||
for (let i = 0; i < msgs.length; i++) {
|
||
const content = msgs[i]?.content;
|
||
if (!Array.isArray(content)) continue;
|
||
const first = content[0] as TextBlock | undefined;
|
||
const isHistory = first?.type === 'text' && first.text === HISTORY_SYNTHETIC_INTRO;
|
||
const hasSlab = content.some(
|
||
(b) => b && (b as TextBlock).type === 'text' && (b as TextBlock).text === '[End of rendered context.]',
|
||
);
|
||
if (isHistory || hasSlab) boundary = i;
|
||
}
|
||
if (boundary < 0) return undefined; // not an imaged-prefix shape — nothing pinned
|
||
const parts: string[] = [];
|
||
if (Array.isArray(req.tools)) for (const t of req.tools) parts.push(JSON.stringify(t));
|
||
const sys = req.system;
|
||
if (typeof sys === 'string') parts.push(sys);
|
||
else if (Array.isArray(sys)) for (const b of sys) parts.push(JSON.stringify(b));
|
||
for (let i = 0; i <= boundary; i++) {
|
||
const content = msgs[i]?.content;
|
||
if (typeof content === 'string') parts.push(content);
|
||
else if (Array.isArray(content))
|
||
for (const b of content) parts.push(typeof b === 'string' ? b : JSON.stringify(b));
|
||
}
|
||
const prefix = parts.join('\x00');
|
||
return { sha8: await sha8(prefix), bytes: prefix.length };
|
||
}
|
||
|
||
/** Best-effort extraction of the CLAUDE.md slab from a system text (heuristic).
|
||
* Returns empty string if nothing CLAUDE.md-shaped is detected. */
|
||
export function extractClaudeMdSlab(staticText: string): string {
|
||
if (!staticText) return '';
|
||
// Headings Claude Code uses around CLAUDE.md content.
|
||
const startPatterns = [
|
||
/^\s*#+\s*Claude\s+Code\s+Rules\s*$/im,
|
||
/^\s*#+\s*CLAUDE\.md\s*$/im,
|
||
/^\s*Claude\s+Code\s+Rules:?\s*$/im,
|
||
];
|
||
let startIdx = -1;
|
||
for (const p of startPatterns) {
|
||
const m = p.exec(staticText);
|
||
if (m && (startIdx === -1 || m.index < startIdx)) startIdx = m.index;
|
||
}
|
||
if (startIdx === -1) return '';
|
||
// End at the next top-level heading or EOF.
|
||
const tail = staticText.slice(startIdx);
|
||
const endMatch = /\n#\s+\S/.exec(tail.slice(1));
|
||
const end = endMatch ? endMatch.index + 1 : tail.length;
|
||
return tail.slice(0, end).trim();
|
||
}
|
||
|
||
/** First user message text, capped at 4 KiB (stable thread id; hashing large pastes is wasteful). */
|
||
export function firstUserText(req: MessagesRequest): string {
|
||
const msgs = req.messages ?? [];
|
||
for (const m of msgs) {
|
||
if (m.role !== 'user') continue;
|
||
if (typeof m.content === 'string') return m.content.slice(0, 4096);
|
||
if (Array.isArray(m.content)) {
|
||
for (const block of m.content) {
|
||
if (block && (block as any).type === 'text' && typeof (block as any).text === 'string') {
|
||
return ((block as any).text as string).slice(0, 4096);
|
||
}
|
||
}
|
||
}
|
||
// First user message found but unreadable — return empty rather than fall through to next.
|
||
return '';
|
||
}
|
||
return '';
|
||
}
|
||
|
||
/** Parse structured fields from the dynamic slab for telemetry. Read-only. */
|
||
export function extractEnvFields(dynamicText: string): EnvFields {
|
||
const out: EnvFields = {};
|
||
if (!dynamicText) return out;
|
||
|
||
const envMatch = /<env>([\s\S]*?)<\/env>/i.exec(dynamicText);
|
||
if (envMatch) {
|
||
const body = envMatch[1]!;
|
||
const cwd = /(?:^|\n)\s*Working directory:\s*(.+?)\s*(?:\n|$)/i.exec(body);
|
||
if (cwd) out.cwd = cwd[1]!.trim();
|
||
const gitRepo = /(?:^|\n)\s*Is directory a git repo:\s*(Yes|No)\b/i.exec(body);
|
||
if (gitRepo) out.isGitRepo = gitRepo[1]!.toLowerCase() === 'yes';
|
||
const platform = /(?:^|\n)\s*Platform:\s*(.+?)\s*(?:\n|$)/i.exec(body);
|
||
if (platform) out.platform = platform[1]!.trim();
|
||
const osVer = /(?:^|\n)\s*OS Version:\s*(.+?)\s*(?:\n|$)/i.exec(body);
|
||
if (osVer) out.osVersion = osVer[1]!.trim();
|
||
const today = /(?:^|\n)\s*Today'?s date:\s*(.+?)\s*(?:\n|$)/i.exec(body);
|
||
if (today) out.today = today[1]!.trim();
|
||
}
|
||
|
||
// Branch may be in <git_status>, <context name="git">, or a bare "Branch:" / "On branch" line.
|
||
const branch =
|
||
/(?:^|\n)\s*(?:On branch|Branch:)\s*([^\s\n]+)/i.exec(dynamicText) ??
|
||
/(?:^|\n)\s*Current branch:\s*([^\s\n]+)/i.exec(dynamicText);
|
||
if (branch) out.gitBranch = branch[1]!.trim();
|
||
|
||
return out;
|
||
}
|
||
|
||
/** Strip the per-turn `x-anthropic-billing-header:` line (changes every turn;
|
||
* must not be baked into the image). Returned as `kept` for the system tail. */
|
||
function stripBillingLine(text: string): { kept: string | null; body: string } {
|
||
const nl = text.indexOf('\n');
|
||
const first = nl === -1 ? text : text.slice(0, nl);
|
||
if (first.startsWith('x-anthropic-billing-header:')) {
|
||
return { kept: first, body: nl === -1 ? '' : text.slice(nl + 1) };
|
||
}
|
||
return { kept: null, body: text };
|
||
}
|
||
|
||
/** Extract the `# Environment` markdown section Claude Code injects into its
|
||
* system text (working dir, git state, platform, model ID). It carries no XML
|
||
* wrapper, so splitStaticDynamic can't catch it — yet its git-status lines
|
||
* change across sessions, and baking them into the slab PNG busts the cross-
|
||
* session cache (system_sha8 717f1fce → 5efaa4bb for a one-file edit). Parallel
|
||
* to stripBillingLine: `kept` re-enters the system tail as plain text. */
|
||
function stripMarkdownEnvSection(text: string): { kept: string; body: string } {
|
||
const m = /(?:^|\n)(# Environment\b[\s\S]*?)(?=\n#{1,6}\s|$)/.exec(text);
|
||
if (!m) return { kept: '', body: text };
|
||
return {
|
||
kept: m[1]!.trimEnd(),
|
||
body: text.slice(0, m.index) + text.slice(m.index + m[0].length),
|
||
};
|
||
}
|
||
|
||
/** Build the "## Tool: name\n<desc>\n```json …```" block for one tool. Docs are
|
||
* imaged on this path (mirrors openai.ts renderToolDoc): the image carries the
|
||
* full schema — annotations included — at image token rates, while tools[]
|
||
* carries the annotation-stripped structure for Anthropic's tool-use validator.
|
||
* (The earlier text-reference design kept this prose-only because schema JSON
|
||
* at text rates would have duplicated what tools[] already pays for; at image
|
||
* rates the duplicate structure is cheap and the stripped annotations are the
|
||
* compression.) */
|
||
function renderToolDoc(t: ToolDef): string {
|
||
const parts: string[] = [`## Tool: ${t.name ?? '?'}`];
|
||
if (t.description) parts.push(t.description);
|
||
if (t.input_schema !== undefined) {
|
||
parts.push('```json\n' + JSON.stringify(t.input_schema) + '\n```');
|
||
}
|
||
return parts.join('\n');
|
||
}
|
||
|
||
function makeImageBlock(pngB64: string, _ephemeral = false): ImageBlock {
|
||
// pxpipe never adds its own cache_control — only moves existing caller markers
|
||
// across the text→image flip. `_ephemeral` is preserved for call-site compat.
|
||
return {
|
||
type: 'image',
|
||
source: { type: 'base64', media_type: 'image/png', data: pngB64 },
|
||
};
|
||
}
|
||
|
||
// --- paging / truncation ---------------------------------------------------
|
||
// Anthropic caps requests at 100 images. Huge tool_results (find trees,
|
||
// log dumps) are truncated with a paging marker before render.
|
||
|
||
/** Visual rows a single input line will consume after soft-wrap at `cols`. */
|
||
function lineRows(line: string, cols: number): number {
|
||
return Math.max(1, Math.ceil(line.length / cols));
|
||
}
|
||
|
||
/** Visual row count after soft-wrap at `cols`.
|
||
*
|
||
* Only hard `\n` starts a new row. The reflow ↵ sentinel is an inline glyph
|
||
* (see wrapLines in render.ts: "never forces a row break"), so packing many
|
||
* original newlines into one soft-wrapped stream must NOT inflate the row
|
||
* count. Treating ↵ as a break overstated image pages ~6× on reflowed
|
||
* history and flipped profitable collapses to not_profitable. */
|
||
function countVisualRows(text: string, cols: number): number {
|
||
let rows = 0;
|
||
let lineStart = 0;
|
||
const len = text.length;
|
||
for (let i = 0; i <= len; i++) {
|
||
const cc = i < len ? text.charCodeAt(i) : -1;
|
||
if (i === len || cc === 10 /* \n */) {
|
||
const lineLen = i - lineStart;
|
||
// Empty line (consecutive \n) still costs one visual row.
|
||
rows += lineLen === 0 ? 1 : Math.ceil(lineLen / Math.max(1, cols));
|
||
lineStart = i + 1;
|
||
}
|
||
}
|
||
return rows;
|
||
}
|
||
|
||
/** Estimate how many images `text` will render to at the given column width.
|
||
* Counts soft-wrapped visual rows, which is what render.ts actually budgets
|
||
* against. Exported for tests + the paging gate.
|
||
*
|
||
* `numCols` (default 1) packs that many text columns side-by-side per
|
||
* image — must match the `multiCol` setting wired through to the renderer
|
||
* for the math to predict the actual image count. */
|
||
export function estimateImageCount(
|
||
textOrLen: string | number,
|
||
cols: number,
|
||
numCols: number = 1,
|
||
maxCharsPerImage: number = READABLE_CHARS_PER_IMAGE,
|
||
maxLinesPerColumn: number = LINES_PER_IMAGE,
|
||
): number {
|
||
const n = Math.max(1, numCols | 0);
|
||
const readableLinesPerCol = Math.max(1, Math.floor(maxCharsPerImage / Math.max(1, cols)));
|
||
const hardLinesPerCol = Math.max(1, Math.floor(maxLinesPerColumn));
|
||
const linesPerImage = Math.min(hardLinesPerCol, readableLinesPerCol) * n;
|
||
const charBudget = Math.max(1, maxCharsPerImage * n);
|
||
if (typeof textOrLen === 'number') {
|
||
// Back-compat shim — numeric arg gets the looser chars-based estimate.
|
||
return Math.max(1, Math.ceil(textOrLen / charBudget));
|
||
}
|
||
const rows = countVisualRows(textOrLen, cols);
|
||
return Math.max(
|
||
1,
|
||
Math.ceil(rows / linesPerImage),
|
||
Math.ceil(textOrLen.length / charBudget),
|
||
);
|
||
}
|
||
|
||
/** Classify content so we can pick a truncation strategy. Cheap heuristics on
|
||
* the first ~4 KiB. Returns:
|
||
* - `'structured'`: JSON/YAML/diff markers at the top. Truncate tail.
|
||
* - `'log'`: ≥30% of lines start with a log level or timestamp. Truncate middle.
|
||
* - `'other'`: prose, file dumps, etc. Truncate middle.
|
||
* Exported for tests. */
|
||
export function classifyContent(text: string): 'structured' | 'log' | 'other' {
|
||
const head = text.slice(0, 4096);
|
||
const trimmed = head.trimStart();
|
||
if (trimmed.startsWith('{') && /^\{\s*("|\})/.test(trimmed)) return 'structured';
|
||
if (trimmed.startsWith('[') && /^\[\s*("|\{|\[|-?\d|true\b|false\b|null\b|\])/.test(trimmed))
|
||
return 'structured';
|
||
if (trimmed.startsWith('---\n') || trimmed.startsWith('---\r\n')) return 'structured';
|
||
if (trimmed.startsWith('diff --git ') || /^---\s+\S/.test(trimmed)) return 'structured';
|
||
const lines = head.split('\n').slice(0, 40).filter((l) => l.length > 0);
|
||
if (lines.length < 4) return 'other';
|
||
const LOG_LINE =
|
||
/^(\[?(DEBUG|INFO|WARN|WARNING|ERROR|TRACE|FATAL)\]?\b|\d{4}-\d{2}-\d{2}[T ]?|\d{2}:\d{2}:\d{2}\b)/;
|
||
let logHits = 0;
|
||
for (const line of lines) if (LOG_LINE.test(line)) logHits++;
|
||
if (logHits / lines.length >= 0.3) return 'log';
|
||
return 'other';
|
||
}
|
||
|
||
/** Build the paging marker text. The model sees this verbatim INSIDE the
|
||
* rendered image so it can reason about what was elided. */
|
||
function buildPagingMarker(args: {
|
||
originalChars: number;
|
||
originalLines: number;
|
||
originalEstImages: number;
|
||
shownHeadLines: number;
|
||
shownTailLines: number;
|
||
omittedLines: number;
|
||
omittedChars: number;
|
||
}): string {
|
||
const tailNote =
|
||
args.shownTailLines > 0
|
||
? ` Showing first ${args.shownHeadLines} lines and last ${args.shownTailLines} lines.`
|
||
: ` Showing first ${args.shownHeadLines} lines (tail elided).`;
|
||
return (
|
||
`\n\n[ pxpipe paging: omitted ${args.omittedLines.toLocaleString('en-US')} lines ` +
|
||
`(${args.omittedChars.toLocaleString('en-US')} chars) of content here. ` +
|
||
`Original length: ${args.originalChars.toLocaleString('en-US')} chars ` +
|
||
`(${args.originalLines.toLocaleString('en-US')} lines, ~${args.originalEstImages} images).` +
|
||
`${tailNote} ]\n\n`
|
||
);
|
||
}
|
||
|
||
/** Truncate `text` so it renders to roughly `maxImages` images at the given
|
||
* `cols`. Picks head/tail split based on `classifyContent`. Budget measured
|
||
* in visual rows (what render.ts actually slices on). Returns the truncated
|
||
* text (with paging marker embedded) and the count of chars omitted. If
|
||
* `text` already fits, returns unchanged with `omittedChars: 0`. Exported
|
||
* for tests. */
|
||
export function truncateForBudget(
|
||
text: string,
|
||
maxImages: number,
|
||
cols: number,
|
||
numCols: number = 1,
|
||
maxCharsPerImage: number = DENSE_CONTENT_CHARS_PER_IMAGE,
|
||
): { text: string; omittedChars: number; truncated: boolean } {
|
||
const n = Math.max(1, numCols | 0);
|
||
const estImages = estimateImageCount(text, cols, n, maxCharsPerImage);
|
||
if (estImages <= maxImages) return { text, omittedChars: 0, truncated: false };
|
||
const readableLinesPerCol = Math.max(1, Math.floor(maxCharsPerImage / Math.max(1, cols)));
|
||
const totalRowBudget = Math.max(8, maxImages * Math.min(LINES_PER_IMAGE, readableLinesPerCol) * n - 6);
|
||
const totalCharBudget = Math.max(128, maxImages * maxCharsPerImage * n - 512);
|
||
const shape = classifyContent(text);
|
||
// Reflowed text uses NL_SENTINEL (↵ U+21B5) as line separator instead of \n.
|
||
// Split on whichever delimiter the text uses so we can truncate at logical
|
||
// line boundaries rather than treating the entire reflowed blob as one line.
|
||
const nlChar = text.indexOf('\n') >= 0 ? '\n' : NL_SENTINEL;
|
||
const lines = text.split(nlChar);
|
||
const originalLines = lines.length;
|
||
const originalChars = text.length;
|
||
|
||
if (shape === 'structured') {
|
||
let rows = 0;
|
||
let chars = 0;
|
||
let cut = 0;
|
||
for (let i = 0; i < lines.length; i++) {
|
||
const r = lineRows(lines[i]!, cols);
|
||
const c = lines[i]!.length + (i > 0 ? 1 : 0);
|
||
if (rows + r > totalRowBudget || chars + c > totalCharBudget) break;
|
||
rows += r;
|
||
chars += c;
|
||
cut = i + 1;
|
||
}
|
||
if (cut === 0) cut = 1;
|
||
const head = lines.slice(0, cut).join(nlChar);
|
||
const omitted = originalChars - head.length;
|
||
return {
|
||
text:
|
||
head +
|
||
buildPagingMarker({
|
||
originalChars,
|
||
originalLines,
|
||
originalEstImages: estImages,
|
||
shownHeadLines: cut,
|
||
shownTailLines: 0,
|
||
omittedLines: originalLines - cut,
|
||
omittedChars: omitted,
|
||
}),
|
||
omittedChars: omitted,
|
||
truncated: true,
|
||
};
|
||
}
|
||
|
||
// log / other: 60% head, 40% tail.
|
||
const headRowBudget = Math.floor(totalRowBudget * 0.6);
|
||
const tailRowBudget = totalRowBudget - headRowBudget;
|
||
const headCharBudget = Math.floor(totalCharBudget * 0.6);
|
||
const tailCharBudget = totalCharBudget - headCharBudget;
|
||
let headRows = 0;
|
||
let headChars = 0;
|
||
let headCut = 0;
|
||
for (let i = 0; i < lines.length; i++) {
|
||
const r = lineRows(lines[i]!, cols);
|
||
const c = lines[i]!.length + (i > 0 ? 1 : 0);
|
||
if (headRows + r > headRowBudget || headChars + c > headCharBudget) break;
|
||
headRows += r;
|
||
headChars += c;
|
||
headCut = i + 1;
|
||
}
|
||
if (headCut === 0) headCut = 1;
|
||
let tailRows = 0;
|
||
let tailChars = 0;
|
||
let tailStart = lines.length;
|
||
for (let i = lines.length - 1; i >= headCut; i--) {
|
||
const r = lineRows(lines[i]!, cols);
|
||
const c = lines[i]!.length + (i < lines.length - 1 ? 1 : 0);
|
||
if (tailRows + r > tailRowBudget || tailChars + c > tailCharBudget) break;
|
||
tailRows += r;
|
||
tailChars += c;
|
||
tailStart = i;
|
||
}
|
||
if (tailStart <= headCut || tailStart >= lines.length) {
|
||
const head = lines.slice(0, headCut).join(nlChar);
|
||
const omitted = originalChars - head.length;
|
||
return {
|
||
text:
|
||
head +
|
||
buildPagingMarker({
|
||
originalChars,
|
||
originalLines,
|
||
originalEstImages: estImages,
|
||
shownHeadLines: headCut,
|
||
shownTailLines: 0,
|
||
omittedLines: originalLines - headCut,
|
||
omittedChars: omitted,
|
||
}),
|
||
omittedChars: omitted,
|
||
truncated: true,
|
||
};
|
||
}
|
||
const headText = lines.slice(0, headCut).join(nlChar);
|
||
const tailText = lines.slice(tailStart).join(nlChar);
|
||
const shownChars = headText.length + tailText.length;
|
||
const omitted = originalChars - shownChars;
|
||
return {
|
||
text:
|
||
headText +
|
||
buildPagingMarker({
|
||
originalChars,
|
||
originalLines,
|
||
originalEstImages: estImages,
|
||
shownHeadLines: headCut,
|
||
shownTailLines: lines.length - tailStart,
|
||
omittedLines: originalLines - headCut - (lines.length - tailStart),
|
||
omittedChars: omitted,
|
||
}) +
|
||
tailText,
|
||
omittedChars: omitted,
|
||
truncated: true,
|
||
};
|
||
}
|
||
|
||
/**
|
||
* Render text → Anthropic image blocks for the proxy. The column-selection rule below
|
||
* (shrink, then single-col unless the content fills the width) is mirrored exactly by
|
||
* the public SDK primitive `renderTextToImages` (library.ts), so the proxy and the
|
||
* `pxpipe export` CLI emit byte-identical PNGs for the same text. Exported so
|
||
* export-proxy-align.test.ts can pin that invariant against the real proxy code.
|
||
*/
|
||
export async function textToImageBlocks(
|
||
text: string,
|
||
cols: number,
|
||
numCols: number = 1,
|
||
/** Shrink canvas to the longest wrapped line. `false` for the slab path
|
||
* (fills full `cols` for multi-col packing). Default `true`. */
|
||
shrinkWidth: boolean = true,
|
||
): Promise<{
|
||
blocks: ImageBlock[];
|
||
/** Raw PNG bytes parallel to `blocks` (avoids re-decoding base64 for dashboard). */
|
||
pngs: Uint8Array[];
|
||
/** Pixel dimensions parallel to `pngs`. */
|
||
dims: Array<{ width: number; height: number }>;
|
||
droppedChars: number;
|
||
droppedCodepoints: Map<number, number>;
|
||
/** Σ width×height — caller accumulates into `info.imagePixels` for px/token regression. */
|
||
pixels: number;
|
||
}> {
|
||
// Shrink before the numCols branch so gate and renderer see the same canvas width.
|
||
// If shrinkage drops below the full width, stay single-col (avoid wasting a divider column).
|
||
const effectiveCols = shrinkWidth ? shrinkColsToContent(text, cols) : cols;
|
||
const effectiveNumCols = effectiveCols < cols ? 1 : numCols;
|
||
const imgs =
|
||
effectiveNumCols > 1
|
||
? await renderTextToPngsMultiCol(text, effectiveCols, effectiveNumCols)
|
||
// Single-col dense: shrink the 384-col base to content so the renderer matches the
|
||
// gate (denseGateGeometry uses DENSE_CONTENT_COLS, priced via shrinkColsToContent).
|
||
// Was hard-coded to DENSE_CONTENT_COLS, which threw away the shrink the gate assumed.
|
||
: await renderTextToPngsWithCharLimit(text, shrinkColsToContent(text, DENSE_CONTENT_COLS), DENSE_CONTENT_CHARS_PER_IMAGE, DENSE_RENDER_STYLE);
|
||
let droppedChars = 0;
|
||
let pixels = 0;
|
||
const droppedCodepoints = new Map<number, number>();
|
||
const blocks: ImageBlock[] = [];
|
||
for (const img of imgs) {
|
||
blocks.push(makeImageBlock(bytesToBase64(img.png), false));
|
||
droppedChars += img.droppedChars;
|
||
pixels += img.width * img.height;
|
||
for (const [cp, n] of img.droppedCodepoints) {
|
||
droppedCodepoints.set(cp, (droppedCodepoints.get(cp) ?? 0) + n);
|
||
}
|
||
}
|
||
return {
|
||
blocks,
|
||
pngs: imgs.map((i) => i.png),
|
||
dims: imgs.map((i) => ({ width: i.width, height: i.height })),
|
||
droppedChars,
|
||
droppedCodepoints,
|
||
pixels,
|
||
};
|
||
}
|
||
|
||
/** Best-effort byte-count of an image block's PNG payload (decoded from b64).
|
||
* Used only for the imageBytes telemetry; an exact value isn't worth a
|
||
* second base64 round-trip. */
|
||
function approxBlockBytes(blk: ImageBlock): number {
|
||
const b64 = blk.source.data;
|
||
// base64 → bytes: every 4 chars decode to 3 bytes, minus padding.
|
||
const pad = b64.endsWith('==') ? 2 : b64.endsWith('=') ? 1 : 0;
|
||
return Math.floor((b64.length * 3) / 4) - pad;
|
||
}
|
||
|
||
// --- main transform --------------------------------------------------------
|
||
|
||
|
||
/**
|
||
* Run history-image compression on `req.messages` and finalize the body.
|
||
* Called from both the main path AND early-exit paths (below_min_chars,
|
||
* not_profitable) — history collapse must run even when the slab skips.
|
||
* Tolerant to missing/short message arrays (collapseHistory short-circuits). */
|
||
async function runHistoryCollapseAndFinalize(
|
||
req: MessagesRequest,
|
||
info: TransformInfo,
|
||
o: Required<TransformOptions>,
|
||
opts: TransformOptions,
|
||
droppedCodepoints: Map<number, number>,
|
||
): Promise<{ body: Uint8Array; info: TransformInfo; collapsed: boolean }> {
|
||
let collapsedFlag = false;
|
||
if (Array.isArray(req.messages) && req.messages.length > 0) {
|
||
const historyCpt = opts.charsPerToken !== undefined
|
||
? o.charsPerToken
|
||
: HISTORY_CHARS_PER_TOKEN;
|
||
const horizon = Math.max(1, Math.floor(o.historyAmortizationHorizon));
|
||
// Pass the symmetric warm-cache burn through to the history-collapse
|
||
// gate as well. The slab gate alone got the symmetric treatment, which
|
||
// let the history gate flip a session out of image mode even when
|
||
// symmetric burn would have kept the slab gate in. Production data
|
||
// 2026-05-23 showed three-turn sessions paying cache_create every
|
||
// turn because the history gate ignored priorWarmImageTokens.
|
||
const historyProfitable = (text: string, cols: number): boolean => {
|
||
// History always renders single-col at the dense 384-col / 240-row page
|
||
// (history.ts → renderTextToPngsWithCharLimit with DENSE_CONTENT_COLS /
|
||
// DENSE_CONTENT_CHARS_PER_IMAGE), so gate at THAT geometry, not o.cols.
|
||
const g = denseGateGeometry(cols, 1);
|
||
return isCompressionProfitableAmortized(
|
||
text, g.cols, undefined, 1, historyCpt, horizon,
|
||
o.priorWarmTokens, o.priorWarmImageTokens, true, g.maxChars,
|
||
);
|
||
};
|
||
// No protectedPrefix here: this path runs only when the slab did NOT image
|
||
// (it stays as text in req.system), so there is no slab message to shield —
|
||
// collapsing from the head is correct.
|
||
const { messages: newMessages, info: histInfo } = await collapseHistory(
|
||
req.messages,
|
||
historyProfitable,
|
||
{ cols: o.cols, protectedPrefix: 0, reflow: o.reflow },
|
||
);
|
||
if (histInfo.collapsedTurns > 0) {
|
||
req.messages = newMessages;
|
||
info.collapsedTurns = histInfo.collapsedTurns;
|
||
info.collapsedChars = histInfo.collapsedChars;
|
||
info.collapsedImages = histInfo.collapsedImages;
|
||
info.imageCount += histInfo.collapsedImages;
|
||
info.imageBytes += histInfo.collapsedImageBytes;
|
||
info.imagePixels = (info.imagePixels ?? 0) + histInfo.collapsedImagePixels;
|
||
// Register the rendered (colored) history PNGs into the dashboard image ring
|
||
// so they are visible, not merely counted. Every other image path feeds this.
|
||
// imagePngs + imageDims must be pushed in lockstep (ring reads them parallel).
|
||
(info.imagePngs ??= []).push(...histInfo.collapsedPngs);
|
||
(info.imageDims ??= []).push(...histInfo.collapsedImageDims);
|
||
info.droppedChars = (info.droppedChars ?? 0) + histInfo.droppedChars;
|
||
for (const [cp, n] of histInfo.droppedCodepoints) {
|
||
droppedCodepoints.set(cp, (droppedCodepoints.get(cp) ?? 0) + n);
|
||
}
|
||
info.historyReason = 'collapsed';
|
||
info.historyTextChars = histInfo.collapsedChars;
|
||
info.historyImageSha = await historyImageSha8(newMessages);
|
||
bumpBucket(info, 'history', histInfo.collapsedChars);
|
||
collapsedFlag = true;
|
||
} else if (histInfo.reason) {
|
||
info.historyReason = histInfo.reason;
|
||
}
|
||
}
|
||
info.outgoingTextChars = countOutgoingTextChars(req);
|
||
const outBody = new TextEncoder().encode(JSON.stringify(req));
|
||
return { body: outBody, info, collapsed: collapsedFlag };
|
||
}
|
||
|
||
/**
|
||
* Rewrite a Messages API request body. Returns the new body (still JSON
|
||
* bytes) plus diagnostic info. On any error, returns the original bytes
|
||
* unchanged.
|
||
*/
|
||
export async function transformRequest(
|
||
body: Uint8Array,
|
||
opts: TransformOptions = {},
|
||
): Promise<{ body: Uint8Array; info: TransformInfo }> {
|
||
// Merge caller opts over DEFAULTS, but treat explicit `undefined` as "not
|
||
// provided" so it falls through to the default. Without this, a caller that
|
||
// passes `{ minToolResultChars: undefined }` (common when forwarding partial
|
||
// options from upstream — e.g. ocproxy's handler) would silently disable the
|
||
// tool_result text-passthrough gate and route everything through the
|
||
// renderer.
|
||
const merged: TransformOptions = { ...DEFAULTS, ...opts };
|
||
for (const k of Object.keys(merged) as (keyof TransformOptions)[]) {
|
||
if (merged[k] === undefined) {
|
||
(merged as Record<string, unknown>)[k] = (DEFAULTS as Record<string, unknown>)[k];
|
||
}
|
||
}
|
||
const o: Required<TransformOptions> = merged as Required<TransformOptions>;
|
||
const info: TransformInfo = {
|
||
compressed: false,
|
||
origChars: 0,
|
||
compressedChars: 0,
|
||
imageCount: 0,
|
||
imageBytes: 0,
|
||
staticChars: 0,
|
||
dynamicChars: 0,
|
||
dynamicBlockCount: 0,
|
||
droppedChars: 0,
|
||
};
|
||
// Per-request codepoint drop histogram. Merged from every render call
|
||
// (static slab + reminder + tool_result compressions). Serialized to
|
||
// `info.droppedCodepointsTop` at the end of transformRequest IF non-empty.
|
||
const droppedCodepoints = new Map<number, number>();
|
||
|
||
if (!o.compress) {
|
||
info.reason = 'compress=false';
|
||
return { body, info };
|
||
}
|
||
|
||
let req: MessagesRequest;
|
||
try {
|
||
req = JSON.parse(new TextDecoder().decode(body));
|
||
} catch (e) {
|
||
info.reason = `parse_error: ${(e as Error).message}`;
|
||
return { body, info };
|
||
}
|
||
|
||
// 1. Pull system text out. Split into:
|
||
// - billingLine: Claude Code's per-turn random header (must NOT be cached).
|
||
// - dynamicText: <env>/<context>/... blocks (per-turn, kept as text).
|
||
// - staticText: everything else (cacheable, goes into the image).
|
||
const systemStaticCacheControl = lastStaticSystemCacheControl(req.system);
|
||
const { text: rawSysText, kept: sysRemainder } = extractSystemText(req.system);
|
||
const { kept: billingLine, body: sysBodyWithEnv } = stripBillingLine(rawSysText);
|
||
// Pull the volatile `# Environment` markdown section out BEFORE the
|
||
// static/dynamic split so per-session git state never reaches the slab image.
|
||
const { kept: envMarkdown, body: sysBody } = stripMarkdownEnvSection(sysBodyWithEnv);
|
||
const {
|
||
staticText,
|
||
dynamicText,
|
||
blockCount: dynBlocks,
|
||
unknownTags,
|
||
staticTagContents,
|
||
} = splitStaticDynamic(sysBody);
|
||
info.staticChars = staticText.length;
|
||
info.dynamicChars = dynamicText.length + envMarkdown.length;
|
||
info.dynamicBlockCount = dynBlocks;
|
||
if (unknownTags.length > 0) info.unknownStaticTags = unknownTags;
|
||
// Parse env fields out of the dynamic slab — telemetry only, never mutates.
|
||
const env = extractEnvFields(dynamicText);
|
||
if (Object.keys(env).length > 0) info.env = env;
|
||
|
||
// Privacy-safe fingerprints that don't depend on tool docs (computed
|
||
// here so they're available even if we below_min_chars out below).
|
||
// systemSha8 is set later, after we know the combined image-bound text.
|
||
const claudeMdSlab = extractClaudeMdSlab(staticText);
|
||
const firstUser = firstUserText(req);
|
||
const [claudeMdSha, firstUserSha] = await Promise.all([
|
||
claudeMdSlab ? sha8(claudeMdSlab) : Promise.resolve(undefined),
|
||
firstUser ? sha8(firstUser) : Promise.resolve(undefined),
|
||
]);
|
||
if (claudeMdSha) info.claudeMdSha8 = claudeMdSha;
|
||
if (firstUserSha) info.firstUserSha8 = firstUserSha;
|
||
|
||
// Canary: slab tags whose content churns within a session bust the image
|
||
// cache every turn — report them regardless of the hardcoded lists.
|
||
if (staticTagContents.size > 0) {
|
||
const churning = observeStaticTagChurn(
|
||
firstUserSha ?? claudeMdSha ?? 'global',
|
||
staticTagContents,
|
||
);
|
||
if (churning.length > 0) info.churningStaticTags = churning;
|
||
}
|
||
|
||
// 2. Move tool docs into the imaged "Tool Reference", stubbing originals.
|
||
// Imaged (not text) because that IS the compression — descriptions and
|
||
// schema annotations ride at image token rates, mirroring the GPT path.
|
||
// Tool docs are static per session, so the slab image stays byte-stable
|
||
// and cache-friendly. Each stub description cites its own heading
|
||
// ("## Tool: <name>") so the model can link stub → full doc
|
||
// deterministically.
|
||
let toolDocsText = '';
|
||
let toolsRewritten: ToolDef[] | undefined;
|
||
if (o.compressTools && Array.isArray(req.tools) && req.tools.length > 0) {
|
||
const docs: string[] = [];
|
||
toolsRewritten = req.tools.map((t) => {
|
||
docs.push(renderToolDoc(t));
|
||
// tools[] keeps the annotation-STRIPPED schema: structure (type/properties/
|
||
// required/enum/items) stays for Anthropic's tool-use validator — a bare
|
||
// {type:'object'} stub caused 400s on non-interactive turns where Anthropic
|
||
// deep-validates with no prior tool_use history to short-circuit. The
|
||
// stripped annotations (description/title/examples/default) ride in the
|
||
// imaged reference instead, at image rates. If stripping yields no
|
||
// structural keys, keep the ORIGINAL schema untouched: it's tiny without
|
||
// properties, and a bare stub is the riskier trade.
|
||
let schema = t.input_schema;
|
||
if (schema && typeof schema === 'object') {
|
||
const stripped = stripSchemaDescriptions(schema, 0) as Record<string, unknown> | null;
|
||
if (stripped && typeof stripped === 'object' && schemaHasStructure(stripped)) {
|
||
schema = stripped;
|
||
}
|
||
}
|
||
// Read-before-Edit precondition rides as LIVE TEXT, not imaged: the CLI
|
||
// rejects Edit/Write on any existing file not Read in THIS session's
|
||
// process, and the rule lost salience once full tool docs moved into the
|
||
// imaged reference (read-gate audit, 2026-07-03). Three tools only, no
|
||
// banned wording — stays clear of the per-tool-stub repetition pattern
|
||
// that tripped reasoning_extraction (see wording note below).
|
||
const readFirstNote = READ_FIRST_TOOLS.has(t.name ?? '')
|
||
? ' Requires a Read of the same file earlier in THIS session when the file' +
|
||
' already exists — the call is rejected otherwise; file content recalled' +
|
||
' from imaged or prior-session context does not satisfy this.'
|
||
: '';
|
||
return {
|
||
...t,
|
||
// Wording note (do NOT reintroduce "system prompt"/"authoritative" — same ban
|
||
// as the imaged-slab banner below): a stub citing "...the Tool Reference
|
||
// section of the system prompt", repeated once per tool, retripped Anthropic's
|
||
// reasoning_extraction refusal (stop_reason: "refusal" → Claude Code fell back
|
||
// to claude-opus-4-8 immediately on cold start, 2026-07-02). The reference
|
||
// block's own header says where the docs live; the stub only needs the heading.
|
||
description: `ⓘ Full docs: see "## Tool: ${t.name ?? '?'}" in the Tool Reference section.${readFirstNote}`,
|
||
...(schema !== undefined ? { input_schema: schema } : {}),
|
||
};
|
||
});
|
||
toolDocsText = docs.join('\n\n');
|
||
info.toolDocsChars = toolDocsText.length;
|
||
}
|
||
|
||
// Static slab + Tool Reference go into the renderer; dynamic slab and billing
|
||
// line stay as plain text so the cache key (= image bytes) is stable across
|
||
// turns. The reference header carries the same first-party provenance framing
|
||
// that defused the imaged-slab banner refusal (169521c): pxpipe names itself
|
||
// as the author of the relocation so the block reads as this session's own
|
||
// config, not a replayed/extracted prompt.
|
||
const toolReferenceText = toolDocsText
|
||
? '=== TOOL REFERENCE ===\n' +
|
||
"pxpipe (this user's local proxy) moved the full tool documentation for this" +
|
||
' session here to reduce token cost. Each tool in the tools list carries a short' +
|
||
' stub description pointing here; the entry under the matching' +
|
||
' "## Tool: <name>" heading below is the complete description for that tool.\n\n' +
|
||
toolDocsText +
|
||
'\n=== END TOOL REFERENCE ==='
|
||
: '';
|
||
const combinedRaw = [staticText, toolReferenceText]
|
||
.filter((s) => s.length > 0)
|
||
.join('\n\n');
|
||
// Compact then reflow before the gate; gate/renderer/paging all see the same text.
|
||
// origChars anchored to raw length — that's what Anthropic would have billed.
|
||
const combined = maybeReflow(compactSlabWhitespace(combinedRaw), o.reflow);
|
||
info.origChars = combinedRaw.length;
|
||
info.compressedChars = 0;
|
||
if (combined) info.systemSha8 = await sha8(combined);
|
||
|
||
if (combined.length < o.minCompressChars) {
|
||
info.reason = `below_min_chars (${combined.length} < ${o.minCompressChars})`;
|
||
// Even with a static slab below the gate, message history may still be
|
||
// collapsable. Run history collapse on the in-memory request so
|
||
// production Codex traffic (tiny system, huge messages) still benefits.
|
||
// If history collapses, we flip `info.compressed = true` and let the
|
||
// library wrapper return reason='applied'; otherwise this still
|
||
// populates `outgoingTextChars` for the regression denominator.
|
||
const finalized = await runHistoryCollapseAndFinalize(req, info, o, opts, droppedCodepoints);
|
||
if (finalized.collapsed) {
|
||
info.compressed = true;
|
||
return { body: finalized.body, info };
|
||
}
|
||
return { body, info };
|
||
}
|
||
|
||
// Break-even check guards even the slab (rare edge: tiny tool docs + tiny slab < 10k chars).
|
||
// numCols clamped to 2000 px width cap; falls back to 1 if even 2 cols would exceed it.
|
||
const numCols = Math.min(
|
||
Math.max(1, (o.multiCol | 0) || 1),
|
||
Math.max(1, maxFittingCols(o.cols)),
|
||
);
|
||
// Gate geometry for dense single-col (tool_result/reminder) paths — 384-col/240-row.
|
||
const denseGeo = denseGateGeometry(o.cols, numCols);
|
||
// Use slab cpt (2.0) unless host pinned charsPerToken explicitly.
|
||
const slabCpt = opts.charsPerToken !== undefined
|
||
? o.charsPerToken
|
||
: SLAB_CHARS_PER_TOKEN;
|
||
// Shrink canvas to longest actual line — pure function of (text, cols) so the
|
||
// cache prefix stays byte-identical across turns. The banner sets a natural width floor.
|
||
const reflowNoteImg = o.reflow
|
||
? ' The glyph ↵ (U+21B5) marks an original hard line break in content — treat as a real newline.'
|
||
: '';
|
||
const columnNoteImg =
|
||
numCols > 1
|
||
? ` Multi-column layout (${numCols} cols): read column 1 (leftmost) top-to-bottom, then column 2, etc.`
|
||
: '';
|
||
// Wording note (do NOT reintroduce "system prompt"/"authoritative"): a user-turn
|
||
// banner announcing "SYSTEM PROMPT ... treat as authoritative system instructions"
|
||
// tripped Anthropic's reasoning_extraction refusal (reads as a replayed/extracted
|
||
// prompt -> model-cloning heuristic) and forced a fallback-model switch. First-party
|
||
// provenance framing below keeps obedience without the extraction signature.
|
||
const imageInstructionHeader =
|
||
'=================== SESSION CONFIGURATION PAGES ===================\n' +
|
||
"pxpipe (this user's local proxy) rendered this session's configuration" +
|
||
' into the following images to reduce token cost. Read the pages carefully and follow them as' +
|
||
' your operating instructions for this session.' +
|
||
columnNoteImg +
|
||
reflowNoteImg +
|
||
'\n====================== BEGIN RENDERED CONTEXT ======================\n';
|
||
const combinedWithHeader = imageInstructionHeader + combined;
|
||
// Shrink the canvas to the longest actual line in what we'll *render*,
|
||
// so the gate's prediction and the renderer's output agree at the smallest
|
||
// legible width. The banner above sets the natural floor — no separate
|
||
// minWidth knob needed. Multi-col packing still gets numCols × this width.
|
||
const slabCols = shrinkColsToContent(combinedWithHeader, o.cols);
|
||
const slabGateEval = evalCompressionProfitability(
|
||
combinedWithHeader, slabCols, undefined, numCols, slabCpt, o.priorWarmTokens, o.priorWarmImageTokens,
|
||
false, // already shrunk — don't double-shrink
|
||
);
|
||
if (slabGateEval) {
|
||
info.gateEval = {
|
||
site: 'slab',
|
||
imageTokens: slabGateEval.imageTokens,
|
||
textTokens: slabGateEval.textTokens,
|
||
burnImageSide: slabGateEval.burnImageSide,
|
||
burnTextSide: slabGateEval.burnTextSide,
|
||
profitable: slabGateEval.profitable,
|
||
};
|
||
}
|
||
if (!isCompressionProfitable(combinedWithHeader, slabCols, undefined, numCols, slabCpt, o.priorWarmTokens, o.priorWarmImageTokens, false)) {
|
||
info.reason = `not_profitable (slab=${combined.length} chars)`;
|
||
bumpPassthrough(info, 'not_profitable');
|
||
// Slab not profitable but history may still be collapsable — try before returning.
|
||
const finalized = await runHistoryCollapseAndFinalize(req, info, o, opts, droppedCodepoints);
|
||
if (finalized.collapsed) {
|
||
info.compressed = true;
|
||
return { body: finalized.body, info };
|
||
}
|
||
return { body, info };
|
||
}
|
||
|
||
// Instruction header co-renders into the same PNG (+1.04pp L1 OCR vs baseline;
|
||
// single-modal framing keeps encoder in image-reading mode for both header + content).
|
||
// Header text is continuous prose (no hard \n) so the renderer soft-wraps densely.
|
||
// 3. Render to PNGs at slabCols width (banner sets natural floor).
|
||
const images =
|
||
numCols > 1
|
||
? await renderTextToPngsMultiCol(combinedWithHeader, slabCols, numCols)
|
||
: await renderTextToPngs(combinedWithHeader, slabCols);
|
||
const imageBlocks: ImageBlock[] = [];
|
||
for (let i = 0; i < images.length; i++) {
|
||
const img = images[i]!;
|
||
const b64 = bytesToBase64(img.png);
|
||
info.imageBytes += img.png.length;
|
||
info.imagePixels = (info.imagePixels ?? 0) + img.width * img.height;
|
||
info.droppedChars = (info.droppedChars ?? 0) + img.droppedChars;
|
||
for (const [cp, n] of img.droppedCodepoints) {
|
||
droppedCodepoints.set(cp, (droppedCodepoints.get(cp) ?? 0) + n);
|
||
}
|
||
const imageBlock = makeImageBlock(b64, i === images.length - 1);
|
||
imageBlocks.push(
|
||
i === images.length - 1 && systemStaticCacheControl !== undefined
|
||
? { ...imageBlock, cache_control: systemStaticCacheControl }
|
||
: imageBlock,
|
||
);
|
||
}
|
||
info.imageCount = imageBlocks.length;
|
||
// Credit raw (pre-compaction) length — what Anthropic would have billed.
|
||
info.compressedChars += combinedRaw.length;
|
||
bumpBucket(info, 'static_slab', combinedRaw.length);
|
||
if (images.length > 0) {
|
||
info.firstImagePng = images[0]!.png;
|
||
info.firstImageWidth = images[0]!.width;
|
||
info.firstImageHeight = images[0]!.height;
|
||
(info.imagePngs ??= []).push(...images.map((i) => i.png));
|
||
(info.imageDims ??= []).push(...images.map((i) => ({ width: i.width, height: i.height })));
|
||
info.imageSourceText = combinedWithHeader.slice(0, 65_536);
|
||
}
|
||
|
||
// 4. Splice images back into the request. OCR framing is baked into the image.
|
||
//
|
||
// Volatile env/context text (git status, cwd, date) must NOT ride in
|
||
// req.system: Anthropic's cache prefix order is tools → system → messages,
|
||
// so system bytes sit BEFORE the slab anchor and any git-state change
|
||
// cold-restarted the whole anchored prefix (48.8% of cold-create waste,
|
||
// events.jsonl 2026-06-26..07-02). It is carried instead at the END of the
|
||
// last user message — the per-turn live tail that re-caches incrementally
|
||
// anyway — appended late in this function, AFTER history collapse, so it can
|
||
// never be baked into a frozen history chunk. Fallback: if no user message
|
||
// exists to carry it, keep it in system rather than drop content.
|
||
const hasUserMsg = (req.messages ?? []).some((m) => m.role === 'user');
|
||
const volatileEnvParts: string[] = [];
|
||
if (dynamicText) volatileEnvParts.push(dynamicText);
|
||
if (envMarkdown) volatileEnvParts.push(envMarkdown);
|
||
const volatileEnvText = hasUserMsg ? volatileEnvParts.join('\n\n') : '';
|
||
|
||
// Images go into first user message — system field rejects images (400 system.N.type).
|
||
{
|
||
const sysTail: SystemField = [];
|
||
// billingLine is session-stable (warm reads through the anchored prefix
|
||
// confirm it; a per-turn value here would zero every cache read).
|
||
if (billingLine) sysTail.push({ type: 'text', text: billingLine });
|
||
if (!hasUserMsg) {
|
||
if (dynamicText) sysTail.push({ type: 'text', text: dynamicText });
|
||
if (envMarkdown) sysTail.push({ type: 'text', text: envMarkdown });
|
||
}
|
||
if (Array.isArray(sysRemainder)) sysTail.push(...sysRemainder);
|
||
// Tool Reference now rides INSIDE the imaged slab (combinedRaw above) — no
|
||
// text splice here. Stubbed tools[] descriptions cite the "## Tool: <name>"
|
||
// headings inside the image; stub ↔ reference invariant holds because both
|
||
// are applied on this same path (gate-fail paths return earlier with
|
||
// original tools untouched).
|
||
req.system = sysTail.length > 0 ? sysTail : undefined;
|
||
|
||
const firstUserIdx = (req.messages ?? []).findIndex((m) => m.role === 'user');
|
||
if (firstUserIdx >= 0) {
|
||
const m = req.messages![firstUserIdx]!;
|
||
const existing = Array.isArray(m.content)
|
||
? m.content
|
||
: [{ type: 'text' as const, text: m.content }];
|
||
|
||
// 5a. Compress <system-reminder> text blocks. cache_control on source text
|
||
// moves to the LAST produced image (pxpipe never adds its own markers).
|
||
const processedExisting: ContentBlock[] = [];
|
||
if (o.compressReminders) {
|
||
for (const blk of existing) {
|
||
const isReminderText =
|
||
blk &&
|
||
(blk as TextBlock).type === 'text' &&
|
||
typeof (blk as TextBlock).text === 'string' &&
|
||
(blk as TextBlock).text.trimStart().startsWith('<system-reminder>');
|
||
if (!isReminderText) {
|
||
processedExisting.push(blk);
|
||
continue;
|
||
}
|
||
// Caller fidelity override: pin this block as text, skip imaging.
|
||
if (callerKeepsSharp(o.keepSharp, { kind: 'reminder', text: (blk as TextBlock).text })) {
|
||
bumpPassthrough(info, 'kept_sharp');
|
||
info.keptSharpBlocks = (info.keptSharpBlocks ?? 0) + 1;
|
||
processedExisting.push(blk);
|
||
continue;
|
||
}
|
||
const textLen = (blk as TextBlock).text.length;
|
||
if (textLen < o.minReminderChars) {
|
||
// Below coarse threshold; can't possibly be profitable. Skip.
|
||
bumpPassthrough(info, 'below_threshold');
|
||
processedExisting.push(blk);
|
||
continue;
|
||
}
|
||
// Lossless whitespace compaction — same dynamics as the system
|
||
// slab: every newline costs ≥1 visual row regardless of column
|
||
// width, so stripped trailing whitespace + collapsed blank-line
|
||
// runs reduce real renderer cost without changing what the
|
||
// model reads.
|
||
const reminderRaw = (blk as TextBlock).text;
|
||
const reminderText = maybeReflow(compactSlabWhitespace(reminderRaw), o.reflow);
|
||
if (!isCompressionProfitable(reminderText, denseGeo.cols, undefined, numCols, o.charsPerToken, 0, 0, true, denseGeo.maxChars)) {
|
||
bumpPassthrough(info, 'not_profitable');
|
||
processedExisting.push(blk);
|
||
continue;
|
||
}
|
||
const { blocks: imgs, pngs: rawPngs, dims: rawDims, droppedChars, droppedCodepoints: dcp, pixels } =
|
||
await textToImageBlocks(reminderText, o.cols, numCols);
|
||
(info.imagePngs ??= []).push(...rawPngs);
|
||
(info.imageDims ??= []).push(...rawDims);
|
||
const srcCacheControl = (blk as { cache_control?: unknown }).cache_control;
|
||
for (let i = 0; i < imgs.length; i++) {
|
||
const img = imgs[i]!;
|
||
const out =
|
||
i === imgs.length - 1 && srcCacheControl !== undefined
|
||
? { ...img, cache_control: srcCacheControl }
|
||
: img;
|
||
processedExisting.push(out as ImageBlock);
|
||
info.imageBytes += approxBlockBytes(img);
|
||
}
|
||
const reminderFactSheet = factSheetText(reminderRaw);
|
||
if (reminderFactSheet) processedExisting.push({ type: 'text', text: reminderFactSheet });
|
||
info.imagePixels = (info.imagePixels ?? 0) + pixels;
|
||
info.reminderImgs = (info.reminderImgs ?? 0) + imgs.length;
|
||
await recordRecoverable(info, o.emitRecoverable, {
|
||
kind: 'reminder',
|
||
text: reminderRaw,
|
||
imageCount: imgs.length,
|
||
});
|
||
info.compressedChars += reminderRaw.length;
|
||
bumpBucket(info, 'reminder', reminderRaw.length);
|
||
info.imageCount += imgs.length;
|
||
info.droppedChars = (info.droppedChars ?? 0) + droppedChars;
|
||
for (const [cp, n] of dcp) {
|
||
droppedCodepoints.set(cp, (droppedCodepoints.get(cp) ?? 0) + n);
|
||
}
|
||
}
|
||
} else {
|
||
processedExisting.push(...existing);
|
||
}
|
||
|
||
const slabFactSheet = factSheetText(combinedRaw);
|
||
m.content = [
|
||
...imageBlocks,
|
||
...(slabFactSheet ? [{ type: 'text' as const, text: slabFactSheet }] : []),
|
||
{ type: 'text' as const, text: '[End of rendered context.]' },
|
||
...processedExisting,
|
||
];
|
||
}
|
||
|
||
// 5b. Compress tool_result content across ALL user messages.
|
||
if (o.compressToolResults) {
|
||
for (const msg of req.messages ?? []) {
|
||
if (msg.role !== 'user' || !Array.isArray(msg.content)) continue;
|
||
const rewritten: ContentBlock[] = [];
|
||
let changed = false;
|
||
for (const blk of msg.content) {
|
||
if (blk && (blk as ToolResultBlock).type === 'tool_result') {
|
||
const tr = blk as ToolResultBlock;
|
||
// Anthropic rejects images inside is_error tool_results — leave alone.
|
||
if (tr.is_error === true) {
|
||
rewritten.push(blk);
|
||
continue;
|
||
}
|
||
const innerRaw = tr.content;
|
||
if (typeof innerRaw === 'string') {
|
||
// Caller fidelity override: pin this tool_result as text.
|
||
if (callerKeepsSharp(o.keepSharp, { kind: 'tool_result', text: innerRaw, toolUseId: tr.tool_use_id })) {
|
||
bumpPassthrough(info, 'kept_sharp');
|
||
info.keptSharpBlocks = (info.keptSharpBlocks ?? 0) + 1;
|
||
rewritten.push(blk);
|
||
continue;
|
||
}
|
||
const inner = compactSlabWhitespace(innerRaw);
|
||
// classifyContent sees pre-reflow `inner` so shape bucketing reflects real structure.
|
||
const innerR = maybeReflow(inner, o.reflow);
|
||
if (innerR.length < o.minToolResultChars) {
|
||
bumpPassthrough(info, 'below_threshold');
|
||
rewritten.push(blk);
|
||
} else if (!isCompressionProfitable(innerR, denseGeo.cols, o.maxImagesPerToolResult, numCols, o.charsPerToken, 0, 0, true, denseGeo.maxChars)) {
|
||
bumpPassthrough(info, 'not_profitable');
|
||
rewritten.push(blk);
|
||
} else {
|
||
// Paging: truncate before render if it would blow the image cap.
|
||
const paged = truncateForBudget(innerR, o.maxImagesPerToolResult, denseGeo.cols, numCols, denseGeo.maxChars);
|
||
if (paged.truncated) {
|
||
info.truncatedToolResults = (info.truncatedToolResults ?? 0) + 1;
|
||
info.omittedChars = (info.omittedChars ?? 0) + paged.omittedChars;
|
||
}
|
||
const { blocks: imgs, pngs: rawPngs, dims: rawDims, droppedChars, droppedCodepoints: dcp, pixels } =
|
||
await textToImageBlocks(paged.text, o.cols, numCols);
|
||
(info.imagePngs ??= []).push(...rawPngs);
|
||
(info.imageDims ??= []).push(...rawDims);
|
||
for (const img of imgs) info.imageBytes += approxBlockBytes(img);
|
||
info.imagePixels = (info.imagePixels ?? 0) + pixels;
|
||
info.toolResultImgs = (info.toolResultImgs ?? 0) + imgs.length;
|
||
info.imageCount += imgs.length;
|
||
await recordRecoverable(info, o.emitRecoverable, {
|
||
kind: 'tool_result',
|
||
toolUseId: tr.tool_use_id,
|
||
text: innerRaw,
|
||
imageCount: imgs.length,
|
||
});
|
||
info.compressedChars += innerRaw.length; // original length = what text billing would be
|
||
info.droppedChars = (info.droppedChars ?? 0) + droppedChars;
|
||
for (const [cp, n] of dcp) {
|
||
droppedCodepoints.set(cp, (droppedCodepoints.get(cp) ?? 0) + n);
|
||
}
|
||
const trFactSheet = factSheetText(innerRaw);
|
||
rewritten.push({
|
||
...tr,
|
||
content: trFactSheet ? [...imgs, { type: 'text' as const, text: trFactSheet }] : imgs,
|
||
});
|
||
changed = true;
|
||
bumpBucket(info, toolResultBucket(classifyContent(inner)), innerRaw.length);
|
||
}
|
||
} else if (Array.isArray(innerRaw)) {
|
||
const newInner: Array<TextBlock | ImageBlock> = [];
|
||
let innerChanged = false;
|
||
for (const ib of innerRaw) {
|
||
const isTextBlock =
|
||
ib &&
|
||
(ib as TextBlock).type === 'text' &&
|
||
typeof (ib as TextBlock).text === 'string';
|
||
if (!isTextBlock) {
|
||
newInner.push(ib as TextBlock | ImageBlock);
|
||
continue;
|
||
}
|
||
const innerTextRaw = (ib as TextBlock).text;
|
||
// Caller fidelity override: pin this tool_result part as text.
|
||
if (callerKeepsSharp(o.keepSharp, { kind: 'tool_result_part', text: innerTextRaw, toolUseId: tr.tool_use_id })) {
|
||
bumpPassthrough(info, 'kept_sharp');
|
||
info.keptSharpBlocks = (info.keptSharpBlocks ?? 0) + 1;
|
||
newInner.push(ib as TextBlock | ImageBlock);
|
||
continue;
|
||
}
|
||
// Lossless whitespace compaction before gate + render.
|
||
const innerText = compactSlabWhitespace(innerTextRaw);
|
||
// R3: gate/page/render on reflowed text; classify pre-reflow.
|
||
const innerTextR = maybeReflow(innerText, o.reflow);
|
||
if (innerTextR.length < o.minToolResultChars) {
|
||
bumpPassthrough(info, 'below_threshold');
|
||
newInner.push(ib as TextBlock | ImageBlock);
|
||
continue;
|
||
}
|
||
if (!isCompressionProfitable(innerTextR, denseGeo.cols, o.maxImagesPerToolResult, numCols, o.charsPerToken, 0, 0, true, denseGeo.maxChars)) {
|
||
bumpPassthrough(info, 'not_profitable');
|
||
newInner.push(ib as TextBlock | ImageBlock);
|
||
continue;
|
||
}
|
||
const paged = truncateForBudget(innerTextR, o.maxImagesPerToolResult, denseGeo.cols, numCols, denseGeo.maxChars);
|
||
if (paged.truncated) {
|
||
info.truncatedToolResults = (info.truncatedToolResults ?? 0) + 1;
|
||
info.omittedChars = (info.omittedChars ?? 0) + paged.omittedChars;
|
||
}
|
||
const { blocks: imgs, pngs: rawPngs, dims: rawDims, droppedChars, droppedCodepoints: dcp, pixels } =
|
||
await textToImageBlocks(paged.text, o.cols, numCols);
|
||
(info.imagePngs ??= []).push(...rawPngs);
|
||
(info.imageDims ??= []).push(...rawDims);
|
||
const srcCacheControl = (ib as { cache_control?: unknown }).cache_control;
|
||
for (let i = 0; i < imgs.length; i++) {
|
||
const img = imgs[i]!;
|
||
const out =
|
||
i === imgs.length - 1 && srcCacheControl !== undefined
|
||
? { ...img, cache_control: srcCacheControl }
|
||
: img;
|
||
newInner.push(out as ImageBlock);
|
||
info.imageBytes += approxBlockBytes(img);
|
||
}
|
||
const partFactSheet = factSheetText(innerTextRaw);
|
||
if (partFactSheet) newInner.push({ type: 'text', text: partFactSheet });
|
||
info.imagePixels = (info.imagePixels ?? 0) + pixels;
|
||
info.toolResultImgs = (info.toolResultImgs ?? 0) + imgs.length;
|
||
info.imageCount += imgs.length;
|
||
await recordRecoverable(info, o.emitRecoverable, {
|
||
kind: 'tool_result_part',
|
||
toolUseId: tr.tool_use_id,
|
||
text: innerTextRaw,
|
||
imageCount: imgs.length,
|
||
});
|
||
info.compressedChars += innerTextRaw.length;
|
||
info.droppedChars = (info.droppedChars ?? 0) + droppedChars;
|
||
for (const [cp, n] of dcp) {
|
||
droppedCodepoints.set(cp, (droppedCodepoints.get(cp) ?? 0) + n);
|
||
}
|
||
bumpBucket(info, toolResultBucket(classifyContent(innerText)), innerTextRaw.length);
|
||
innerChanged = true;
|
||
}
|
||
if (innerChanged) {
|
||
rewritten.push({ ...tr, content: newInner });
|
||
changed = true;
|
||
} else {
|
||
rewritten.push(blk);
|
||
}
|
||
} else {
|
||
rewritten.push(blk);
|
||
}
|
||
} else {
|
||
rewritten.push(blk);
|
||
}
|
||
}
|
||
if (changed) msg.content = rewritten;
|
||
}
|
||
}
|
||
}
|
||
|
||
if (toolsRewritten) req.tools = toolsRewritten;
|
||
|
||
// 6. History-image compression (always runs after per-message rewrites).
|
||
// History is single-col dense; use slab cpt unless host pinned charsPerToken.
|
||
// protectedPrefix excludes the slab-bearing first user message — collapsing it
|
||
// would reduce slab images to [image] placeholders and destroy the cache anchor.
|
||
if (Array.isArray(req.messages) && req.messages.length > 0) {
|
||
const historyCpt = opts.charsPerToken !== undefined
|
||
? o.charsPerToken
|
||
: HISTORY_CHARS_PER_TOKEN;
|
||
const horizon = Math.max(1, Math.floor(o.historyAmortizationHorizon));
|
||
const historyProfitable = (text: string, cols: number): boolean => {
|
||
// Gate at dense 384-col/240-row geometry (matches history.ts renderer).
|
||
const g = denseGateGeometry(cols, 1);
|
||
return isCompressionProfitableAmortized(
|
||
text, g.cols, undefined, 1, historyCpt, horizon,
|
||
o.priorWarmTokens, o.priorWarmImageTokens, true, g.maxChars,
|
||
);
|
||
};
|
||
const slabAnchorIdx = (req.messages ?? []).findIndex((m) => m.role === 'user');
|
||
const { messages: newMessages, info: histInfo } = await collapseHistory(
|
||
req.messages,
|
||
historyProfitable,
|
||
{ cols: o.cols, protectedPrefix: slabAnchorIdx >= 0 ? slabAnchorIdx + 1 : 0, reflow: o.reflow },
|
||
);
|
||
if (histInfo.collapsedTurns > 0) {
|
||
req.messages = newMessages;
|
||
info.collapsedTurns = histInfo.collapsedTurns;
|
||
info.collapsedChars = histInfo.collapsedChars;
|
||
info.collapsedImages = histInfo.collapsedImages;
|
||
info.imageCount += histInfo.collapsedImages;
|
||
info.imageBytes += histInfo.collapsedImageBytes;
|
||
info.imagePixels = (info.imagePixels ?? 0) + histInfo.collapsedImagePixels;
|
||
// Register the rendered (colored) history PNGs into the dashboard image ring
|
||
// so they are visible, not merely counted. Every other image path feeds this.
|
||
// imagePngs + imageDims must be pushed in lockstep (ring reads them parallel).
|
||
(info.imagePngs ??= []).push(...histInfo.collapsedPngs);
|
||
(info.imageDims ??= []).push(...histInfo.collapsedImageDims);
|
||
info.droppedChars = (info.droppedChars ?? 0) + histInfo.droppedChars;
|
||
for (const [cp, n] of histInfo.droppedCodepoints) {
|
||
droppedCodepoints.set(cp, (droppedCodepoints.get(cp) ?? 0) + n);
|
||
}
|
||
info.historyReason = 'collapsed';
|
||
info.historyTextChars = histInfo.collapsedChars;
|
||
info.historyImageSha = await historyImageSha8(newMessages);
|
||
bumpBucket(info, 'history', histInfo.collapsedChars);
|
||
// Move the single cache anchor onto the history image so slab + history
|
||
// cache as one stable prefix (created once, then read), instead of the
|
||
// history image re-creating whenever the caller's downstream marker moves.
|
||
//
|
||
// ONLY when collapseHistory pinned a byte-frozen carry-over chunk. On the
|
||
// session's FIRST collapse the range fits in one freeze window, no carry-over
|
||
// exists (ordinal undefined), and relocating would land the anchor on the
|
||
// newest still-growing history image — a volatile breakpoint that forced a
|
||
// one-time full-prefix rewrite (~53k tokens/session). Leave the anchor on
|
||
// the byte-stable slab image until a frozen chunk exists to pin to.
|
||
if (histInfo.carryOverImageOrdinal !== undefined) {
|
||
relocateAnchorToHistoryImage(req.messages, histInfo.carryOverImageOrdinal);
|
||
}
|
||
} else if (histInfo.reason) {
|
||
info.historyReason = histInfo.reason;
|
||
}
|
||
}
|
||
|
||
// Volatile env/context text lands at the END of the last user message (see
|
||
// the block above image splice for why). Runs AFTER history collapse so the
|
||
// env bytes stay in the live tail — never imaged into a frozen chunk — and
|
||
// AFTER 5b so they are never run through tool_result compression. Note
|
||
// tool_result blocks legally precede trailing text blocks in a user message
|
||
// (Claude Code appends its own system-reminders the same way).
|
||
//
|
||
// The block is wrapped in <system-reminder> tags so the model (and any
|
||
// human reading a transcript) attributes it as injected context, NOT user
|
||
// prose. Without the wrapper the relocated "# Environment" section blends
|
||
// seamlessly into the user's message — on an empty/short user turn it can
|
||
// BECOME the entire visible message (observed live, 2026-07). The wrapper
|
||
// rides in the volatile tail behind the slab anchor, so it costs ~60 chars
|
||
// per request and cannot perturb the cached prefix. Same-pass safety: 5a
|
||
// (compressReminders) runs earlier and only scans the first user message,
|
||
// so this block is never self-imaged; and pxpipe is stateless per request,
|
||
// so the wrapper never appears in inbound client history (no compounding).
|
||
if (volatileEnvText) {
|
||
const wrappedEnvText = `<system-reminder>\nContext relocated by pxpipe from the system prompt (volatile per-turn environment state — not written by the user):\n\n${volatileEnvText}\n</system-reminder>`;
|
||
const msgs = req.messages ?? [];
|
||
for (let i = msgs.length - 1; i >= 0; i--) {
|
||
const m = msgs[i]!;
|
||
if (m.role !== 'user') continue;
|
||
const content = Array.isArray(m.content)
|
||
? m.content
|
||
: [{ type: 'text' as const, text: m.content }];
|
||
msgs[i] = { ...m, content: [...content, { type: 'text' as const, text: wrappedEnvText }] };
|
||
info.envRelocatedChars = wrappedEnvText.length;
|
||
break;
|
||
}
|
||
}
|
||
|
||
info.compressed = true;
|
||
// Attribution signal for prompt-cache busts (#11): digest the exact pinned
|
||
// prefix we send (history/slab boundary; live tail excluded) AFTER all marker
|
||
// placement — incl. relocateAnchorToHistoryImage — is final. Read-only.
|
||
{
|
||
const pfx = await cachePrefixDigest(req);
|
||
if (pfx) {
|
||
info.cachePrefixSha8 = pfx.sha8;
|
||
info.cachePrefixBytes = pfx.bytes;
|
||
}
|
||
}
|
||
// Top dropped codepoints, capped at 20 entries to bound JSONL row size.
|
||
if (droppedCodepoints.size > 0) {
|
||
const TOP_N = 20;
|
||
const sorted = [...droppedCodepoints.entries()]
|
||
.sort((a, b) => b[1] - a[1])
|
||
.slice(0, TOP_N);
|
||
const out: Record<string, number> = {};
|
||
for (const [cp, count] of sorted) {
|
||
const hex = cp.toString(16).toUpperCase().padStart(4, '0');
|
||
out[`U+${hex}`] = count;
|
||
}
|
||
info.droppedCodepointsTop = out;
|
||
}
|
||
info.outgoingTextChars = countOutgoingTextChars(req);
|
||
const outBody = new TextEncoder().encode(JSON.stringify(req));
|
||
return { body: outBody, info };
|
||
}
|
||
|
||
/** Sum every TEXT char the upstream tokenizer will see (system, tools, messages).
|
||
* Excludes image base64 and redacted_thinking. Denominator for the
|
||
* `tokens ≈ α·outgoingTextChars + β·imagePixels` regression. */
|
||
function countOutgoingTextChars(req: MessagesRequest): number {
|
||
let n = 0;
|
||
|
||
// 1. system field
|
||
const sys = req.system;
|
||
if (typeof sys === 'string') {
|
||
n += sys.length;
|
||
} else if (Array.isArray(sys)) {
|
||
for (const b of sys) {
|
||
if (b && (b as TextBlock).type === 'text' && typeof (b as TextBlock).text === 'string') {
|
||
n += (b as TextBlock).text.length;
|
||
}
|
||
}
|
||
}
|
||
|
||
// 2. tool definitions
|
||
if (Array.isArray(req.tools)) {
|
||
for (const tool of req.tools) {
|
||
if (!tool || typeof tool !== 'object') continue;
|
||
if (typeof tool.name === 'string') n += tool.name.length;
|
||
if (typeof tool.description === 'string') n += tool.description.length;
|
||
if (tool.input_schema !== undefined) {
|
||
n += safeStringifyLen(tool.input_schema);
|
||
}
|
||
}
|
||
}
|
||
|
||
// 3. per-message content
|
||
for (const msg of req.messages ?? []) {
|
||
const c = msg.content;
|
||
if (typeof c === 'string') {
|
||
n += c.length;
|
||
continue;
|
||
}
|
||
if (!Array.isArray(c)) continue;
|
||
for (const b of c) {
|
||
if (!b || typeof b !== 'object') continue;
|
||
const type = (b as { type?: string }).type;
|
||
|
||
if (type === 'text') {
|
||
const tb = b as TextBlock;
|
||
if (typeof tb.text === 'string') n += tb.text.length;
|
||
continue;
|
||
}
|
||
|
||
if (type === 'tool_use') {
|
||
const tu = b as ToolUseBlock;
|
||
if (typeof tu.name === 'string') n += tu.name.length;
|
||
if (tu.input !== undefined) n += safeStringifyLen(tu.input);
|
||
continue;
|
||
}
|
||
|
||
if (type === 'tool_result') {
|
||
const tr = b as ToolResultBlock;
|
||
if (typeof tr.tool_use_id === 'string') n += tr.tool_use_id.length;
|
||
const inner = tr.content;
|
||
if (typeof inner === 'string') {
|
||
n += inner.length;
|
||
} else if (Array.isArray(inner)) {
|
||
for (const ib of inner) {
|
||
if (ib && (ib as TextBlock).type === 'text' && typeof (ib as TextBlock).text === 'string') {
|
||
n += (ib as TextBlock).text.length;
|
||
}
|
||
}
|
||
}
|
||
continue;
|
||
}
|
||
|
||
if (type === 'thinking') {
|
||
const th = b as unknown as { thinking?: unknown };
|
||
if (typeof th.thinking === 'string') n += (th.thinking as string).length;
|
||
continue;
|
||
}
|
||
|
||
// image, redacted_thinking, server_tool_use, etc. — skip.
|
||
}
|
||
}
|
||
|
||
return n;
|
||
}
|
||
|
||
/** JSON.stringify length, tolerant of cycles. Returns 0 on error. */
|
||
function safeStringifyLen(v: unknown): number {
|
||
try {
|
||
return JSON.stringify(v)?.length ?? 0;
|
||
} catch {
|
||
return 0;
|
||
}
|
||
}
|