@xamukavila/pxpipe 0.8.0

package/dist/core/library.js

@@ -0,0 +1,133 @@
+import { isPxpipeSupportedModel } from './applicability.js';
+import { countCacheControlMarkers } from './measurement.js';
+import { renderTextToPngsWithCharLimit, renderTextToPngsMultiCol, measureContentCols, maxFittingCols, reflow, DENSE_CONTENT_COLS, DENSE_CONTENT_CHARS_PER_IMAGE, DENSE_RENDER_STYLE, MAX_HEIGHT_PX, } from './render.js';
+import { transformRequest, } from './transform.js';
+function toUint8Array(bytes) {
+    if (bytes instanceof Uint8Array)
+        return bytes;
+    if (bytes instanceof ArrayBuffer)
+        return new Uint8Array(bytes);
+    return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+function emptyInfo(reason) {
+    return {
+        compressed: false,
+        reason,
+        origChars: 0,
+        compressedChars: 0,
+        imageCount: 0,
+        imageBytes: 0,
+        staticChars: 0,
+        dynamicChars: 0,
+        dynamicBlockCount: 0,
+        droppedChars: 0,
+    };
+}
+function classifyReason(info) {
+    if (info.compressed)
+        return 'applied';
+    const r = info.reason ?? '';
+    if (r.startsWith('parse_error'))
+        return 'parse_error';
+    if (r.startsWith('compress=false'))
+        return 'compress_disabled';
+    if (r.startsWith('below_min_chars'))
+        return 'below_min_chars';
+    if (r.startsWith('below_min_tokens'))
+        return 'below_min_tokens';
+    if (r.startsWith('not_profitable'))
+        return 'not_profitable';
+    if (r.includes('image') && r.includes('limit'))
+        return 'image_limit';
+    return 'passthrough';
+}
+/**
+ * Library wrapper for the Anthropic Messages transformer: model gate, machine-readable
+ * reasons, and cache_control ownership flag (prevents hosts stacking a second injector).
+ */
+export async function transformAnthropicMessages(input) {
+    const original = toUint8Array(input.body);
+    if (!isPxpipeSupportedModel(input.model)) {
+        return {
+            body: original,
+            applied: false,
+            reason: 'unsupported_model',
+            detail: input.model ?? undefined,
+            info: emptyInfo('unsupported_model'),
+            cache: { ownsCacheControl: false, markerCount: countCacheControlMarkers(original) },
+        };
+    }
+    try {
+        const { body, info } = await transformRequest(original, input.options);
+        const reason = classifyReason(info);
+        const markerCount = countCacheControlMarkers(body);
+        return {
+            body,
+            applied: info.compressed,
+            reason,
+            detail: info.reason,
+            info,
+            cache: {
+                ownsCacheControl: info.compressed && markerCount > 0,
+                markerCount,
+            },
+        };
+    }
+    catch (e) {
+        return {
+            body: original,
+            applied: false,
+            reason: 'transform_error',
+            detail: e instanceof Error ? e.message : String(e),
+            info: emptyInfo(`transform_error: ${e instanceof Error ? e.message : String(e)}`),
+            cache: { ownsCacheControl: false, markerCount: countCacheControlMarkers(original) },
+        };
+    }
+}
+/**
+ * Render arbitrary text to dense PNG pages — the public, documented entry for the
+ * renderer the proxy uses internally. Sizes a narrow canvas to the content (`shrink`)
+ * and packs multiple columns (`multiCol`) so short-line content isn't priced at full
+ * width. Returns raw PNG bytes + pixel dimensions, ready to write to disk or wrap in
+ * image blocks. This is the surface SDK consumers should use instead of reaching into
+ * the internal leaf renderers in `render.ts`.
+ */
+export async function renderTextToImages(text, opts = {}) {
+    const maxCols = Math.max(1, (opts.cols ?? DENSE_CONTENT_COLS) | 0);
+    const style = opts.style ?? DENSE_RENDER_STYLE;
+    const maxHeightPx = opts.maxHeightPx ?? MAX_HEIGHT_PX;
+    const maxChars = opts.maxCharsPerImage ?? DENSE_CONTENT_CHARS_PER_IMAGE;
+    // Reflow (the proxy's dense default; opt-in here): minify trailing whitespace + collapse
+    // blank-line runs, then join hard newlines with the ↵ sentinel so short lines PACK into
+    // full-width rows instead of one-line-per-row with a ragged right margin. Indentation is
+    // preserved (minifyForRender only touches trailing ws), so code stays readable and the ↵
+    // marks every real newline so the text is fully reconstructable. This is exactly what the
+    // proxy's history path does before rendering — without it, a 384-col canvas holding ~25-col
+    // code lines wastes ~75% of every row, which is why raw exports looked sparse. reflow()
+    // bails (→ raw text) only if the source already contains ↵, which is vanishingly rare.
+    const source = opts.reflow ? reflow(text) ?? text : text;
+    // Width/columns: measure the content, then pack as many side-by-side columns as fit the
+    // width cap (auto) or the caller's explicit count. Reflowed source is one ↵-joined full-
+    // width line, so this collapses to a single dense 384-col column — byte-identical to the
+    // proxy's history render (renderTextToPngsWithCharLimit at DENSE_CONTENT_COLS).
+    const cols = opts.shrink === false ? maxCols : measureContentCols(source, maxCols);
+    const requestedCols = opts.multiCol === undefined || opts.multiCol === 'auto'
+        ? Math.max(1, maxFittingCols(cols))
+        : Math.max(1, opts.multiCol | 0);
+    const numCols = cols < maxCols ? 1 : requestedCols;
+    const imgs = numCols > 1
+        ? await renderTextToPngsMultiCol(source, cols, numCols)
+        : await renderTextToPngsWithCharLimit(source, cols, maxChars, style, maxHeightPx);
+    let droppedChars = 0;
+    let pixels = 0;
+    for (const im of imgs) {
+        droppedChars += im.droppedChars;
+        pixels += im.width * im.height;
+    }
+    return {
+        pages: imgs.map((im) => ({ png: im.png, width: im.width, height: im.height })),
+        droppedChars,
+        pixels,
+    };
+}
+//# sourceMappingURL=library.js.map

package/dist/core/measurement.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Pure body-shaping utilities for the uncompressed count_tokens counterfactual.
+ * No fetch, auth, or Node APIs — hosts supply their own transport.
+ */
+export interface CountTokensBodies {
+    /** Full original body, filtered to count_tokens-accepted fields. */
+    readonly fullBody: Uint8Array | null;
+    /** Original body truncated at the latest cache_control marker; null when none exists. */
+    readonly cacheablePrefixBody: Uint8Array | null;
+}
+type BytesLike = Uint8Array | ArrayBuffer | ArrayBufferView;
+export declare function buildCountTokensBodies(bytes: BytesLike): CountTokensBodies;
+export declare function buildBaselineCountTokensBody(bytes: BytesLike): Uint8Array | null;
+/** Build a body containing only the longest cacheable prefix (everything up to and including the last
+ *  cache_control marker). count_tokens on this body gives cacheable_prefix_tokens.
+ *  Walk order (latest-first in cache order): messages → system → tools.
+ *  Returns null when no markers exist (cacheable_prefix_tokens = 0). */
+export declare function buildCacheablePrefixCountTokensBody(bytes: BytesLike): Uint8Array | null;
+/** Count cache_control markers anywhere in an Anthropic Messages body. */
+export declare function countCacheControlMarkers(bytes: BytesLike): number;
+export {};
+//# sourceMappingURL=measurement.d.ts.map

package/dist/core/measurement.js

@@ -0,0 +1,213 @@
+/**
+ * Pure body-shaping utilities for the uncompressed count_tokens counterfactual.
+ * No fetch, auth, or Node APIs — hosts supply their own transport.
+ */
+/** Fields accepted by /v1/messages/count_tokens. Any other field returns 400 "Unknown parameter". */
+const COUNT_TOKENS_FIELDS = new Set([
+    'model',
+    'messages',
+    'system',
+    'tools',
+    'tool_choice',
+    'thinking',
+    'mcp_servers',
+]);
+function toUint8Array(bytes) {
+    if (bytes instanceof Uint8Array)
+        return bytes;
+    if (bytes instanceof ArrayBuffer)
+        return new Uint8Array(bytes);
+    return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+export function buildCountTokensBodies(bytes) {
+    const b = toUint8Array(bytes);
+    return {
+        fullBody: buildBaselineCountTokensBody(b),
+        cacheablePrefixBody: buildCacheablePrefixCountTokensBody(b),
+    };
+}
+export function buildBaselineCountTokensBody(bytes) {
+    const b = toUint8Array(bytes);
+    try {
+        const obj = JSON.parse(new TextDecoder().decode(b));
+        const out = {};
+        for (const k of Object.keys(obj)) {
+            if (COUNT_TOKENS_FIELDS.has(k))
+                out[k] = obj[k];
+        }
+        if (typeof out.model !== 'string' || !Array.isArray(out.messages))
+            return null;
+        return new TextEncoder().encode(JSON.stringify(out));
+    }
+    catch {
+        return null;
+    }
+}
+/** True when an object carries a cache_control key (presence only; value ignored). */
+function hasCacheControl(x) {
+    return (typeof x === 'object'
+        && x !== null
+        && x.cache_control != null);
+}
+/** Return tool_use ids with no matching tool_result. count_tokens rejects orphans;
+ *  truncating at a cache_control marker commonly creates them (result is in the dropped tail). */
+function findOrphanToolUseIds(messages) {
+    const uses = [];
+    const results = new Set();
+    for (const msg of messages) {
+        if (!msg || typeof msg !== 'object')
+            continue;
+        const content = msg.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const blk of content) {
+            if (!blk || typeof blk !== 'object')
+                continue;
+            const t = blk.type;
+            if (t === 'tool_use') {
+                const id = blk.id;
+                if (typeof id === 'string')
+                    uses.push(id);
+            }
+            else if (t === 'tool_result') {
+                const id = blk.tool_use_id;
+                if (typeof id === 'string')
+                    results.add(id);
+            }
+        }
+    }
+    return uses.filter((id) => !results.has(id));
+}
+/** Append minimal synthetic tool_results for orphan tool_use ids so count_tokens won't reject the body.
+ *  Adds only a handful of tokens; keeps estimate within ~1% of truth. */
+function appendSyntheticToolResults(truncated) {
+    const messages = truncated.messages;
+    if (!Array.isArray(messages))
+        return truncated;
+    const orphanIds = findOrphanToolUseIds(messages);
+    if (orphanIds.length === 0)
+        return truncated;
+    const syntheticUserMsg = {
+        role: 'user',
+        content: orphanIds.map((id) => ({
+            type: 'tool_result',
+            tool_use_id: id,
+            content: 'ok',
+        })),
+    };
+    return { ...truncated, messages: [...messages, syntheticUserMsg] };
+}
+/** Build a body containing only the longest cacheable prefix (everything up to and including the last
+ *  cache_control marker). count_tokens on this body gives cacheable_prefix_tokens.
+ *  Walk order (latest-first in cache order): messages → system → tools.
+ *  Returns null when no markers exist (cacheable_prefix_tokens = 0). */
+export function buildCacheablePrefixCountTokensBody(bytes) {
+    const b = toUint8Array(bytes);
+    let obj;
+    try {
+        obj = JSON.parse(new TextDecoder().decode(b));
+    }
+    catch {
+        return null;
+    }
+    if (typeof obj.model !== 'string')
+        return null;
+    const system = obj.system;
+    const messages = obj.messages;
+    const tools = obj.tools;
+    let truncated = null;
+    if (Array.isArray(messages)) {
+        for (let mi = messages.length - 1; mi >= 0 && truncated == null; mi--) {
+            const msg = messages[mi];
+            const content = msg?.content;
+            if (Array.isArray(content)) {
+                for (let bi = content.length - 1; bi >= 0; bi--) {
+                    if (hasCacheControl(content[bi])) {
+                        const truncatedMsg = { ...msg, content: content.slice(0, bi + 1) };
+                        const truncatedMessages = messages.slice(0, mi).concat([truncatedMsg]);
+                        truncated = {
+                            model: obj.model,
+                            messages: truncatedMessages,
+                        };
+                        if (system !== undefined)
+                            truncated.system = system;
+                        if (tools !== undefined)
+                            truncated.tools = tools;
+                        break;
+                    }
+                }
+            }
+            else if (hasCacheControl(msg)) {
+                truncated = {
+                    model: obj.model,
+                    messages: messages.slice(0, mi + 1),
+                };
+                if (system !== undefined)
+                    truncated.system = system;
+                if (tools !== undefined)
+                    truncated.tools = tools;
+            }
+        }
+    }
+    if (truncated == null && Array.isArray(system)) {
+        for (let si = system.length - 1; si >= 0; si--) {
+            if (hasCacheControl(system[si])) {
+                truncated = {
+                    model: obj.model,
+                    system: system.slice(0, si + 1),
+                    messages: [{ role: 'user', content: 'x' }],
+                };
+                if (tools !== undefined)
+                    truncated.tools = tools;
+                break;
+            }
+        }
+    }
+    if (truncated == null && Array.isArray(tools)) {
+        for (let ti = tools.length - 1; ti >= 0; ti--) {
+            if (hasCacheControl(tools[ti])) {
+                truncated = {
+                    model: obj.model,
+                    tools: tools.slice(0, ti + 1),
+                    messages: [{ role: 'user', content: 'x' }],
+                };
+                break;
+            }
+        }
+    }
+    if (truncated == null)
+        return null;
+    truncated = appendSyntheticToolResults(truncated);
+    const out = {};
+    for (const k of Object.keys(truncated)) {
+        if (COUNT_TOKENS_FIELDS.has(k))
+            out[k] = truncated[k];
+    }
+    return new TextEncoder().encode(JSON.stringify(out));
+}
+/** Count cache_control markers anywhere in an Anthropic Messages body. */
+export function countCacheControlMarkers(bytes) {
+    const b = toUint8Array(bytes);
+    try {
+        return countCacheControlValue(JSON.parse(new TextDecoder().decode(b)));
+    }
+    catch {
+        return 0;
+    }
+}
+function countCacheControlValue(value) {
+    if (!value || typeof value !== 'object')
+        return 0;
+    let n = hasCacheControl(value) ? 1 : 0;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            n += countCacheControlValue(item);
+    }
+    else {
+        for (const item of Object.values(value)) {
+            n += countCacheControlValue(item);
+        }
+    }
+    return n;
+}
+//# sourceMappingURL=measurement.js.map

package/dist/core/openai-history.d.ts

@@ -0,0 +1,124 @@
+/**
+ * GPT history-image compression.
+ *
+ * The static system+tool slab is small (~30k chars); the bulk of a GPT agent
+ * request is the conversation transcript, which OpenCode resends in full every
+ * turn — the Responses API is driven statelessly here (no `previous_response_id`),
+ * so turns 1..N-1 are re-sent as plain text on turn N. pxpipe collapses the OLD
+ * closed-tool-call prefix of that transcript into 1-N PNG images and keeps the
+ * recent tail as text.
+ *
+ * OpenAI prompt-caching is automatic and prefix-based: no `cache_control`
+ * breakpoints, no 1.25× write premium, cached reads at ~0.1×. The collapse
+ * boundary is snapped to a chunk grid so the history image stays byte-identical
+ * across turns and keeps hitting that automatic cache (the same flap-avoidance
+ * trick src/core/history.ts uses for Anthropic).
+ *
+ * This mirrors src/core/history.ts but operates on Responses `input` items and
+ * Chat `messages` rather than Anthropic Message blocks. The two formats differ
+ * enough (function_call/function_call_output vs tool_calls/tool role) that a
+ * shared block type isn't worth it; instead each format is lowered to a common
+ * HistoryTurn list and the planner/renderer are shared.
+ */
+import { type RenderedImage } from './render.js';
+/** Break-even gate predicate, injected to avoid a circular import with openai.ts.
+ *  Receives the full string (not length) so the renderer's row-aware image-count
+ *  estimate sees real newlines — history text is newline-heavy. */
+export type GptProfitableFn = (text: string, cols: number) => boolean;
+export interface GptHistoryOptions {
+    /** Trailing items kept as live text (never collapsed). */
+    keepTail: number;
+    /** Minimum collapsible items in [protectedPrefix..boundary]; below this the
+     *  cache-amortization math doesn't pay (imaging a tiny prefix is net cost). */
+    minCollapsePrefix: number;
+    /** Minimum collapsed-text size in o200k TOKENS (not chars). OpenAI caches the
+     *  text transcript at ~0.1× already and bills images by vision tokens, so the
+     *  break-even is a token comparison — 8000 chars of dense JSON tokenizes very
+     *  differently from 8000 chars of prose. Below this, imaging a tiny prefix is
+     *  net cost. */
+    minCollapseTokens: number;
+    /** Soft-wrap columns for the dense renderer. */
+    cols: number;
+    /** Advance the collapse boundary in steps of this many items so the rendered
+     *  PNG stays byte-identical across turns and keeps hitting the prompt cache.
+     *  0 = per-item moving boundary (cache-hostile; tests only). */
+    collapseChunk: number;
+    /** Render the collapse range as independent image chunks of this many turns on
+     *  an ABSOLUTE grid anchored at protectedPrefix. A completed chunk's bytes are
+     *  fixed by its turn range alone, so old chunks stay byte-identical (cache_read
+     *  forever) as the conversation grows — only the newest partial chunk
+     *  re-renders. 0 = render the whole range as one blob (legacy, non-append-only). */
+    freezeChunk: number;
+    /** Target size of one frozen image SECTION, in o200k tokens. The collapse range
+     *  is cut into sections by walking turns from protectedPrefix and sealing a
+     *  section each time its cumulative token count crosses this target. A sealed
+     *  section's bytes are a pure function of its turn range (independent of where
+     *  the conversation currently ends), so it stays byte-identical — and OpenAI
+     *  prefix-cache-hits — as the conversation grows. Leftover tail turns that don't
+     *  fill a whole section are left UNCOLLAPSED (live text) until they do. Chosen so
+     *  each section renders to roughly one ≤6000px image, well under gpt-5.x's
+     *  10,000-patch `detail:original` budget. Turn size, not turn count, drives this. */
+    sectionTokens: number;
+    /** Max rendered image height in px (per-model; from the GPT profile). Threaded
+     *  into renderTextToPngs so history pages split at the same height the gate prices. */
+    maxHeightPx: number;
+    /** Hard cap on GPT history image count. This is a TRUE cap, not a threshold:
+     *  collapse the oldest completed sections until the next section would exceed
+     *  the cap, then leave the remaining history as ordinary text. Prevents 80+
+     *  image gpt-5.5 requests without dropping context or live tool state. */
+    maxImages: number;
+    /** Reflow the transcript before rendering: pack soft-wrapped lines and mark
+     *  every hard newline with the ↵ sentinel — same treatment as the static
+     *  slab. History text is newline-heavy (role headers, JSON args), so without
+     *  this each short line wastes a full render row and no ↵ marker appears.
+     *  The returned `text` (o200k baseline + cache byte-stability) stays the
+     *  ORIGINAL, un-reflowed transcript. */
+    reflow: boolean;
+}
+export declare const GPT_HISTORY_DEFAULTS: GptHistoryOptions;
+/** One conversation item lowered to a renderable unit. */
+export interface HistoryTurn {
+    /** Serialized text (with role header / tool markers). Empty = skip (e.g. reasoning). */
+    text: string;
+    /** Tool-call ids this item opens (function_call / assistant tool_calls). */
+    openIds: string[];
+    /** Tool-call ids this item closes (function_call_output / tool message). */
+    closeIds: string[];
+    /** Item we can't safely serialize (unknown kind, item_reference) — a hard
+     *  barrier: never collapse across it, since dropping it could lose state. */
+    opaque: boolean;
+    /** Raw body when this item is a real USER request (role==='user', not a tool
+     *  result). The planner pins the MOST RECENT such turn as legible text instead
+     *  of imaging it, so the live ask is never OCR-only. undefined = not a user turn. */
+    userText?: string;
+}
+export interface GptCollapsePlan {
+    /** Rendered history images BEFORE the pinned user turn (or ALL images when no
+     *  turn was pinned). Empty when no collapse happened. */
+    images: RenderedImage[];
+    /** Rendered history images AFTER the pinned user turn. Empty unless a pin split
+     *  the range. Total imaged = images ∪ imagesAfter. */
+    imagesAfter: RenderedImage[];
+    /** Raw text of the most-recent user request, kept legible (NOT imaged) and
+     *  spliced between `images` and `imagesAfter`. undefined = nothing pinned. */
+    pinText?: string;
+    /** The collapsed transcript text that was rendered (for o200k token counting). */
+    text: string;
+    /** Inclusive start index into the original item array. */
+    start: number;
+    /** Exclusive end index. Caller splices [start, endExclusive) → one synthetic item. */
+    endExclusive: number;
+    collapsedTurns: number;
+    collapsedChars: number;
+    reason?: 'prefix_too_short' | 'no_closed_prefix' | 'below_min_tokens' | 'not_profitable' | 'too_many_images' | 'render_empty';
+    droppedChars: number;
+    droppedCodepoints: Map<number, number>;
+}
+/**
+ * Plan + render a history collapse over pre-lowered turns. Pure w.r.t. the input
+ * (caller does the splice and builds the format-specific synthetic item).
+ */
+export declare function planGptCollapse(turns: HistoryTurn[], protectedPrefix: number, isProfitable: GptProfitableFn, opts?: Partial<GptHistoryOptions>): Promise<GptCollapsePlan>;
+export declare function responsesItemsToTurns(items: unknown[]): HistoryTurn[];
+export declare function chatMessagesToTurns(messages: unknown[]): HistoryTurn[];
+//# sourceMappingURL=openai-history.d.ts.map