@xamukavila/pxpipe 0.8.0

package/dist/core/factsheet.js

@@ -0,0 +1,216 @@
+/**
+ * Verbatim fact-sheet for imaged content.
+ *
+ * When pxpipe renders a block (system slab, history, tool_result, reminder) to a PNG,
+ * the precision-critical, hard-to-OCR strings inside it — file paths, URLs, SHAs/UUIDs,
+ * version numbers, CLI flags, large numbers, CONST_IDS — are exactly what a model is
+ * most likely to misread off the image yet most likely to need quoted verbatim. This
+ * module extracts those tokens so they ride next to the image as plain text: the model
+ * quotes them without re-reading the PNG, and they stay in the cached prefix.
+ *
+ * Deterministic by construction (fixed pattern order, length-desc/lexical sort, no
+ * Date/random) → the emitted text is byte-stable across turns and never busts the
+ * Anthropic prompt cache. Empirically ~5% of source chars on production history
+ * (median 4.9%, max 12.1%, N=10), which preserves the imaging token win.
+ */
+/** ReDoS-safe extraction patterns (each global). Ordered most- to least-specific so the
+ *  longest, most-identifying tokens are kept first when the substring filter runs. */
+const PATTERNS = [
+    /\bhttps?:\/\/[^\s)"'<>]+/g, // URLs
+    /\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b/g, // UUID
+    /(?:[\w@~+-]+)?(?:\/[\w.@+-]+)+\.[A-Za-z]\w{0,8}\b/g, // path with a file extension (multi-dot ok: .test.ts)
+    /\/[\w.@+-]+(?:\/[\w.@+-]+)+\/?/g, // dir path (>=2 segments)
+    /\b(?=[0-9a-f]*\d)[0-9a-f]{7,40}\b/g, // git sha / long hex (must contain a digit)
+    /\bv?\d+\.\d+(?:\.\d+)?(?:[-+][\w.]+)?\b/g, // version string
+    /(?:^|[^\w-])(--?[A-Za-z][\w-]+)/g, // CLI flag (token in capture group 1)
+    /\b\d[\d,_]{3,}\b/g, // large / separated number
+    /\b\d+\.\d+\b/g, // decimal
+    /\b[A-Z][A-Z0-9]{2,}(?:_[A-Z0-9]+)+\b/g, // CONST_IDS / env var names
+    // Ticket/advisory-style codes: uppercase hyphenated with ≥1 digit (PROJ-1482,
+    // CVE-2024-30078, AUDIT-ZX9). Digit lookahead is bounded → no backtracking blowup.
+    /\b(?=[A-Z0-9-]{0,119}\d)[A-Z][A-Z0-9]+(?:-[A-Z0-9]+)+\b/g,
+];
+const MIN_LEN = 3;
+const MAX_LEN = 120;
+/** Budget cap: highest-priority tokens kept first. Exported so consumers can report drops. */
+export const MAX_TOKENS = 64;
+// At most this many URL exemplars: URLs are long, structured, low OCR-risk, and usually
+// reconstructable, so they must never crowd out short zero-redundancy tokens.
+const MAX_URLS = 8;
+const MAX_SEEN = 2048; // defensive bound on distinct tokens entering substring-collapse
+const MAX_SCAN = 262_144; // defensive input bound; tool_results are already paged
+const MAX_CHUNK = 512; // whitespace-free chunks longer than this are blobs (base64, minified) — skip
+/** Budget priority by token SHAPE, not length — length is anti-correlated with
+ *  OCR-risk×consequence: a 70-char URL is structured and reconstructable, while a 7-char
+ *  hex SHA or a port has zero redundancy and fails silently when misread. So short opaque
+ *  identifiers outrank long URLs when the budget is tight. Pure + total → deterministic →
+ *  cache-stable. Tiers: 0 = protect always, 1 = paths/versions/misc, 2 = URLs (cap + last). */
+const SHAPE_UUID = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+const SHAPE_HEX = /^(?=[0-9a-f]*\d)[0-9a-f]{7,40}$/; // git sha / opaque hex
+const SHAPE_CONST = /^[A-Z][A-Z0-9]{2,}(?:_[A-Z0-9]+)+$/; // CONST_IDS / env vars
+const SHAPE_TICKET = /^(?=[A-Z0-9-]*\d)[A-Z][A-Z0-9]+(?:-[A-Z0-9]+)+$/; // PROJ-1482 / CVE-2024-30078
+const SHAPE_FLAG = /^--?[A-Za-z][\w-]+$/; // CLI flag
+const SHAPE_NUM = /^\d[\d,_]*$|^\d+\.\d+$/; // port / large or separated number / decimal
+const SHAPE_URL = /^https?:\/\//;
+/** Lower tier = higher keep-priority. Pure function of the token → deterministic. */
+function priorityTier(tok) {
+    if (SHAPE_HEX.test(tok) ||
+        SHAPE_UUID.test(tok) ||
+        SHAPE_CONST.test(tok) ||
+        SHAPE_TICKET.test(tok) ||
+        SHAPE_FLAG.test(tok) ||
+        SHAPE_NUM.test(tok)) {
+        return 0;
+    }
+    if (SHAPE_URL.test(tok))
+        return 2;
+    return 1;
+}
+/**
+ * Extract deduped, precision-critical tokens from `text`. Substrings of a longer kept
+ * token are dropped (so `/github.com` inside the full URL, `lib/x.ts` inside
+ * `src/lib/x.ts`, etc. collapse to the most specific form); the 64-token budget is then
+ * filled by priority tier (see `priorityTier`) so short, high-consequence tokens are never
+ * evicted by long low-risk URLs.
+ *
+ * Every token class is whitespace-free, so we split on whitespace first and skip
+ * blob-length chunks. That bounds each regex to a short chunk and keeps extraction
+ * strictly O(n) — no quadratic backtracking on delimiter-heavy input like base64 or
+ * minified bundles (which embed `/` and would otherwise make the path patterns blow up).
+ */
+export function extractFactSheetTokens(text) {
+    return extractFactSheetEntries(text).map((e) => e.token);
+}
+/**
+ * Like `extractFactSheetTokens`, but each kept token carries its occurrence count.
+ * Counts make the fact sheet a *quantitative* index: tally questions over imaged
+ * content ("how many lines mention CODE-X?") become answerable from text instead
+ * of from counting rows of 5×8 px glyphs — the one operation page images are worst
+ * at. The kept-token SET and its order are byte-identical to the pre-count
+ * behaviour; only counts are new. Same-token spans matched by two patterns are
+ * deduped by offset so a token is never double-counted.
+ */
+export function extractFactSheetEntries(text) {
+    const scan = text.length > MAX_SCAN ? text.slice(0, MAX_SCAN) : text;
+    const counts = new Map();
+    for (const chunk of scan.split(/\s+/)) {
+        if (chunk.length < MIN_LEN || chunk.length > MAX_CHUNK)
+            continue;
+        // Offset-level dedup WITHIN this chunk: two patterns matching the identical
+        // token at the same position must count once. Keyed by token+start offset.
+        const spanSeen = new Set();
+        for (const re of PATTERNS) {
+            for (const m of chunk.matchAll(re)) {
+                // Strip trailing sentence punctuation pulled in from prose (`pull/93.` → `pull/93`);
+                // no real identifier we extract ends in these.
+                const tok = (m[1] ?? m[0]).trim().replace(/[.,;:!?]+$/, '');
+                if (tok.length < MIN_LEN || tok.length > MAX_LEN)
+                    continue;
+                const key = `${m.index ?? 0}\x00${tok}`;
+                if (spanSeen.has(key))
+                    continue;
+                spanSeen.add(key);
+                counts.set(tok, (counts.get(tok) ?? 0) + 1);
+            }
+        }
+        if (counts.size >= MAX_SEEN)
+            break;
+    }
+    // Phase 1 — substring collapse (length-desc): keep the most-specific form, folding e.g.
+    // a URL's path-portion into the full URL. Cross-tier on purpose. Total order (length,
+    // then lexical) so the result is independent of Set iteration order.
+    const ordered = [...counts.keys()].sort((a, b) => b.length - a.length || (a < b ? -1 : a > b ? 1 : 0));
+    const specific = [];
+    for (const t of ordered) {
+        if (!specific.some((k) => k.includes(t)))
+            specific.push(t);
+    }
+    // Phase 2 — allocate the budget by priority tier (shape, not length) so short,
+    // zero-redundancy tokens (SHAs, ports, flags) can never be evicted by long low-risk URLs.
+    // URLs are kept only as a few exemplars. Comparator is total → byte-stable output.
+    const ranked = specific
+        .map((t) => ({ t, tier: priorityTier(t) }))
+        .sort((a, b) => a.tier - b.tier || b.t.length - a.t.length || (a.t < b.t ? -1 : a.t > b.t ? 1 : 0));
+    const kept = [];
+    let urls = 0;
+    for (const { t, tier } of ranked) {
+        if (kept.length >= MAX_TOKENS)
+            break;
+        if (tier === 2 && urls++ >= MAX_URLS)
+            continue;
+        kept.push(t);
+    }
+    return kept.map((t) => ({ token: t, count: counts.get(t) ?? 1 }));
+}
+/**
+ * Page-aware variant of `extractFactSheetTokens` for large source texts.
+ *
+ * Splits `text` into chunks of `charsPerPage` (use `DENSE_CONTENT_CHARS_PER_IMAGE`
+ * from render.ts for the export pipeline), calls `extractFactSheetTokens` on each
+ * chunk (each chunk is smaller than MAX_SCAN so no truncation occurs), merges the
+ * results across all chunks with first-seen deduplication, then applies a single
+ * global priority-budget pass to select the best MAX_TOKENS identifiers.
+ *
+ * Returns `{ kept, dropped }` where `dropped` is the count of identifiers that
+ * survived extraction across all pages but did not fit in the MAX_TOKENS budget.
+ *
+ * Does NOT mutate the behaviour of `extractFactSheetTokens` or `factSheetText`.
+ */
+export function extractFactSheetTokensAllPages(text, charsPerPage) {
+    const { kept, dropped } = extractFactSheetEntriesAllPages(text, charsPerPage);
+    return { kept: kept.map((e) => e.token), dropped };
+}
+/** Entry-carrying variant of `extractFactSheetTokensAllPages`: same kept set and
+ *  order, with per-token occurrence counts summed across all pages. */
+export function extractFactSheetEntriesAllPages(text, charsPerPage) {
+    const counts = new Map();
+    const all = [];
+    // Walk the text in page-sized chunks. Each chunk is ≤ charsPerPage < MAX_SCAN,
+    // so extractFactSheetEntries will not truncate within a chunk.
+    const pageCount = Math.max(1, Math.ceil(text.length / charsPerPage));
+    for (let i = 0; i < pageCount; i++) {
+        const chunk = text.slice(i * charsPerPage, (i + 1) * charsPerPage);
+        for (const { token, count } of extractFactSheetEntries(chunk)) {
+            if (!counts.has(token))
+                all.push(token);
+            counts.set(token, (counts.get(token) ?? 0) + count);
+        }
+    }
+    // Re-apply the global priority budget so a tier-0 identifier on page 5
+    // is never evicted by many tier-1 tokens from page 1.
+    const ranked = all
+        .map((t) => ({ t, tier: priorityTier(t) }))
+        .sort((a, b) => a.tier - b.tier || b.t.length - a.t.length || (a.t < b.t ? -1 : a.t > b.t ? 1 : 0));
+    const kept = [];
+    let urls = 0;
+    for (const { t, tier } of ranked) {
+        if (kept.length >= MAX_TOKENS)
+            break;
+        if (tier === 2 && urls++ >= MAX_URLS)
+            continue;
+        kept.push({ token: t, count: counts.get(t) ?? 1 });
+    }
+    return { kept, dropped: all.length - kept.length };
+}
+const OPEN = '[Exact identifiers from the rendered context above (paths, ids, versions, numbers) — quote these verbatim instead of transcribing them from the image: ';
+/** Variant used when at least one token repeats — explains the ×N annotation so the
+ *  model can answer tally questions from the sheet instead of counting glyph rows. */
+const OPEN_COUNTS = '[Exact identifiers from the rendered context above (paths, ids, versions, numbers) — quote these verbatim instead of transcribing them from the image; ×N marks a token that occurs N times within the imaged content: ';
+/** Build the one-line fact-sheet string from a pre-extracted token list. */
+export function factSheetTextFromTokens(tokens) {
+    return tokens.length > 0 ? OPEN + tokens.join(' · ') + ']' : '';
+}
+/** Build the one-line fact-sheet string from token+count entries. Byte-identical to
+ *  `factSheetTextFromTokens` when no token repeats, so existing sheets stay cache-stable. */
+export function factSheetTextFromEntries(entries) {
+    if (entries.length === 0)
+        return '';
+    const anyRepeat = entries.some((e) => e.count >= 2);
+    const body = entries.map((e) => (e.count >= 2 ? `${e.token} ×${e.count}` : e.token)).join(' · ');
+    return (anyRepeat ? OPEN_COUNTS : OPEN) + body + ']';
+}
+/** One-line fact-sheet string for `text`, or `''` when nothing notable was found. */
+export function factSheetText(text) {
+    return factSheetTextFromEntries(extractFactSheetEntries(text));
+}
+//# sourceMappingURL=factsheet.js.map

package/dist/core/gpt-model-profiles.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Per-model GPT rendering + vision-cost profiles.
+ *
+ * One place to retune when a new model ships with different image tokenization,
+ * a different downscale threshold (max safe portrait-strip width), or a different
+ * max image height. Every built-in profile is BEHAVIOR-IDENTICAL to the old
+ * hardcoded `resolveVisionCost` + `GPT_STRIP_COLS` + `MAX_HEIGHT_PX`, so existing
+ * cost numbers (1190 / 1445 / 2372 / 1464 / 630 …) are unchanged.
+ *
+ * Retune without a code change via the PXPIPE_GPT_PROFILES env var (JSON map of
+ * model-id PREFIX -> partial profile; longest matching prefix wins, checked
+ * BEFORE the built-in table). Partial fields fall back to the built-in match, so
+ * you can override just one knob:
+ *
+ *   PXPIPE_GPT_PROFILES='{"gpt-5.6":{"vision":{"regime":"patch","multiplier":1,"patchCap":12000},"stripCols":200,"maxHeightPx":2400}}'
+ *   PXPIPE_GPT_PROFILES='{"gpt-5.6":{"stripCols":176}}'   # widen only
+ */
+/**
+ * GPT strip height, DECOUPLED from render.ts's MAX_HEIGHT_PX (which is Anthropic's
+ * 1568-edge / ~1.15 MP clamp). OpenAI's pre-tokenize resize is different: fit within
+ * 2048×2048, then shortest side → 768. A 768-px-wide portrait strip up to 2048 px tall
+ * survives un-resampled, so GPT keeps the taller page. Every built-in cost number below
+ * (1190 / 1445 / 2372 / 1464 / 630 …) was calibrated at this height — do not re-link to
+ * the Anthropic constant.
+ */
+export declare const GPT_MAX_HEIGHT_PX = 1932;
+/** Image-token cost model (mirrors OpenAI's mandatory pre-tokenize resize). */
+export type GptVisionCost = {
+    regime: 'tile';
+    base: number;
+    perTile: number;
+} | {
+    regime: 'patch';
+    multiplier: number;
+    patchCap: number;
+};
+export interface GptModelProfile {
+    /** How OpenAI bills the rendered images as input tokens. */
+    vision: GptVisionCost;
+    /** Max portrait-strip width in COLUMNS before the API downscales (destroying
+     *  5px glyphs). 152 cols x 5px + 8px pad = 768px = OpenAI's shortest-side floor. */
+    stripCols: number;
+    /** Max rendered image height in px. Threaded into the renderer so the gate's
+     *  cost estimate and the actual page split agree. */
+    maxHeightPx: number;
+}
+/** Default downscale-safe strip width (768px). Exported as the global cols default. */
+export declare const DEFAULT_GPT_STRIP_COLS = 152;
+/**
+ * Conservative fallback for unrecognized models: tile 85/170 over-states cost,
+ * which biases the gate toward pass-through (safe). Matches gpt-4o/4.1/4.5.
+ */
+export declare const DEFAULT_GPT_PROFILE: GptModelProfile;
+/**
+ * Resolve the full rendering + vision-cost profile for a model id. Env overrides
+ * (longest matching prefix) win over the built-in table; unknown models get the
+ * conservative `DEFAULT_GPT_PROFILE`.
+ */
+export declare function resolveGptProfile(model: string | null | undefined): GptModelProfile;
+//# sourceMappingURL=gpt-model-profiles.d.ts.map

package/dist/core/gpt-model-profiles.js

@@ -0,0 +1,161 @@
+/**
+ * Per-model GPT rendering + vision-cost profiles.
+ *
+ * One place to retune when a new model ships with different image tokenization,
+ * a different downscale threshold (max safe portrait-strip width), or a different
+ * max image height. Every built-in profile is BEHAVIOR-IDENTICAL to the old
+ * hardcoded `resolveVisionCost` + `GPT_STRIP_COLS` + `MAX_HEIGHT_PX`, so existing
+ * cost numbers (1190 / 1445 / 2372 / 1464 / 630 …) are unchanged.
+ *
+ * Retune without a code change via the PXPIPE_GPT_PROFILES env var (JSON map of
+ * model-id PREFIX -> partial profile; longest matching prefix wins, checked
+ * BEFORE the built-in table). Partial fields fall back to the built-in match, so
+ * you can override just one knob:
+ *
+ *   PXPIPE_GPT_PROFILES='{"gpt-5.6":{"vision":{"regime":"patch","multiplier":1,"patchCap":12000},"stripCols":200,"maxHeightPx":2400}}'
+ *   PXPIPE_GPT_PROFILES='{"gpt-5.6":{"stripCols":176}}'   # widen only
+ */
+/**
+ * GPT strip height, DECOUPLED from render.ts's MAX_HEIGHT_PX (which is Anthropic's
+ * 1568-edge / ~1.15 MP clamp). OpenAI's pre-tokenize resize is different: fit within
+ * 2048×2048, then shortest side → 768. A 768-px-wide portrait strip up to 2048 px tall
+ * survives un-resampled, so GPT keeps the taller page. Every built-in cost number below
+ * (1190 / 1445 / 2372 / 1464 / 630 …) was calibrated at this height — do not re-link to
+ * the Anthropic constant.
+ */
+export const GPT_MAX_HEIGHT_PX = 1932;
+/** Default downscale-safe strip width (768px). Exported as the global cols default. */
+export const DEFAULT_GPT_STRIP_COLS = 152;
+const C = DEFAULT_GPT_STRIP_COLS;
+const H = GPT_MAX_HEIGHT_PX;
+/**
+ * Conservative fallback for unrecognized models: tile 85/170 over-states cost,
+ * which biases the gate toward pass-through (safe). Matches gpt-4o/4.1/4.5.
+ */
+export const DEFAULT_GPT_PROFILE = {
+    vision: { regime: 'tile', base: 85, perTile: 170 },
+    stripCols: C,
+    maxHeightPx: H,
+};
+/** True for the patch-billed mini/nano family (incl. o4-mini). */
+const isMiniNanoPatch = (m) => /^(?:gpt-5(?:\.\d+)?|gpt-4\.1)-(?:mini|nano)/.test(m) || /^o4-mini/.test(m);
+/**
+ * Built-in profiles, evaluated in order (first match wins). Precedence and
+ * numbers reproduce the previous hardcoded `resolveVisionCost` EXACTLY:
+ *   mini/nano -> patch (nano 2.46 / mini 1.62, cap 1536), BEFORE 5.x flagship.
+ */
+const BUILTIN_RULES = [
+    // nano patch models: ceil(patches * 2.46), cap 1536
+    {
+        test: (m) => isMiniNanoPatch(m) && /nano/.test(m),
+        profile: { vision: { regime: 'patch', multiplier: 2.46, patchCap: 1536 }, stripCols: C, maxHeightPx: H },
+    },
+    // mini / o4-mini patch models: ceil(patches * 1.62), cap 1536
+    {
+        test: (m) => isMiniNanoPatch(m) && !/nano/.test(m),
+        profile: { vision: { regime: 'patch', multiplier: 1.62, patchCap: 1536 }, stripCols: C, maxHeightPx: H },
+    },
+    // gpt-5.6 flagship — EXPLICIT slot so the day-one retune is one line (or one env
+    // var). Identical to the generic 5.x rule below until the real numbers land.
+    {
+        test: (m) => /^gpt-5\.6/.test(m),
+        profile: { vision: { regime: 'patch', multiplier: 1, patchCap: 10000 }, stripCols: C, maxHeightPx: H },
+    },
+    // 5.x flagship (gpt-5.4/5.5/…, no -mini/-nano): patch, multiplier 1, detail:original cap
+    {
+        test: (m) => /^gpt-5\.\d/.test(m),
+        profile: { vision: { regime: 'patch', multiplier: 1, patchCap: 10000 }, stripCols: C, maxHeightPx: H },
+    },
+    // gpt-5 / gpt-5-chat-latest: tile 70/140
+    {
+        test: (m) => /^gpt-5/.test(m),
+        profile: { vision: { regime: 'tile', base: 70, perTile: 140 }, stripCols: C, maxHeightPx: H },
+    },
+    // o1 / o3 reasoning: tile 75/150
+    {
+        test: (m) => /^o[13]/.test(m),
+        profile: { vision: { regime: 'tile', base: 75, perTile: 150 }, stripCols: C, maxHeightPx: H },
+    },
+];
+function resolveBuiltin(m) {
+    for (const rule of BUILTIN_RULES)
+        if (rule.test(m))
+            return rule.profile;
+    return DEFAULT_GPT_PROFILE;
+}
+// --- env override (PXPIPE_GPT_PROFILES) -----------------------------------
+// Parsed lazily and memoized on the raw env string so tests can mutate
+// process.env and have it re-read, without re-parsing on every hot-path call.
+let envRaw = null;
+let envMap = new Map();
+function isValidVision(v) {
+    if (!v || typeof v !== 'object')
+        return false;
+    const o = v;
+    if (o.regime === 'tile')
+        return Number.isFinite(o.base) && Number.isFinite(o.perTile);
+    if (o.regime === 'patch')
+        return Number.isFinite(o.multiplier) && Number.isFinite(o.patchCap);
+    return false;
+}
+function posInt(v, fallback) {
+    return Number.isFinite(v) && v > 0 ? Math.floor(v) : fallback;
+}
+function parseEnvProfiles(raw) {
+    const out = new Map();
+    if (!raw)
+        return out;
+    let obj;
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch {
+        return out; // malformed env never throws — fall back to built-ins
+    }
+    if (!obj || typeof obj !== 'object')
+        return out;
+    for (const [k, v] of Object.entries(obj)) {
+        if (!v || typeof v !== 'object')
+            continue;
+        const key = k.toLowerCase();
+        const base = resolveBuiltin(key); // partial fields fall back to the built-in match
+        const p = v;
+        out.set(key, {
+            vision: isValidVision(p.vision) ? p.vision : base.vision,
+            stripCols: posInt(p.stripCols, base.stripCols),
+            maxHeightPx: posInt(p.maxHeightPx, base.maxHeightPx),
+        });
+    }
+    return out;
+}
+function envProfiles() {
+    const raw = (typeof process !== 'undefined' && process.env && process.env.PXPIPE_GPT_PROFILES) || '';
+    if (raw !== envRaw) {
+        envRaw = raw;
+        envMap = parseEnvProfiles(raw);
+    }
+    return envMap;
+}
+/**
+ * Resolve the full rendering + vision-cost profile for a model id. Env overrides
+ * (longest matching prefix) win over the built-in table; unknown models get the
+ * conservative `DEFAULT_GPT_PROFILE`.
+ */
+export function resolveGptProfile(model) {
+    const m = (model ?? '').toLowerCase();
+    const env = envProfiles();
+    if (env.size > 0) {
+        let best;
+        let bestLen = -1;
+        for (const [k, p] of env) {
+            if (m.startsWith(k) && k.length > bestLen) {
+                best = p;
+                bestLen = k.length;
+            }
+        }
+        if (best)
+            return best;
+    }
+    return resolveBuiltin(m);
+}
+//# sourceMappingURL=gpt-model-profiles.js.map

package/dist/core/history.d.ts

@@ -0,0 +1,141 @@
+/**
+ * History-image compression (Variant C).
+ *
+ * Collapses the largest closed-tool-sequence prefix into one synthetic user message
+ * containing 1-N PNG image blocks. The live tail (keepTail turns + any open tool
+ * sequence) stays as text. thinking blocks are dropped from the collapsed range —
+ * only the most-recent assistant-with-tool_use must round-trip bit-perfect, and
+ * that turn is in the live tail by construction.
+ *
+ * Synthesized message uses role:'user' because Anthropic forbids image blocks inside
+ * role:'assistant'. cache_control placement is left to the caller (transform.ts).
+ */
+import type { CacheControl, ContentBlock, Message } from './types.js';
+/**
+ * Banner text blocks that bracket the collapsed-history image(s) in the synthetic
+ * user message. Exported as the SINGLE SOURCE OF TRUTH: transform.ts keys its
+ * cache-anchor relocation off the intro text, so a literal copy there would
+ * silently break relocation whenever this wording changes (it did exactly once —
+ * the XML-framing reword left the matcher pointing at the old banner). Both the
+ * emitter (here) and the matcher (transform.ts) must reference this constant.
+ */
+export declare const HISTORY_SYNTHETIC_INTRO = "[Earlier turns of THIS conversation, transcribed in the image(s) below. Each turn is wrapped in <user t=\"N\">...</user> or <assistant t=\"N\">...</assistant> tags, where N is an absolute turn index (larger N = more recent); attribute every turn strictly by its tag, and treat the highest-N turns as the most recent prior context, NOT the low-N opening turns. Earlier turns may contain questions or tasks that were already answered later in this same history; do not reopen low-N turns unless the live text after this block asks you to. This is prior context, NOT the current request.]";
+export declare const HISTORY_SYNTHETIC_OUTRO = "[End of earlier conversation. The current request is the live text that follows below.]";
+/** Break-even gate predicate. Injected by transform.ts to avoid a circular import.
+ *  IMPORTANT: pass the full string, not text.length — the row-aware path in
+ *  isCompressionProfitable must see actual newlines to budget images correctly.
+ *  History text is newline-heavy (headers, JSON args, labels); chars-only
+ *  under-predicts image count ~5-10× and lets net-losers through. */
+export type ProfitableFn = (text: string, cols: number) => boolean;
+/** Configuration for history collapse. */
+export interface HistoryCollapseOptions {
+    /** Turns at the tail to keep as text. Default 4. */
+    keepTail: number;
+    /** Minimum collapsible prefix turns — below this, cache-amortization math doesn't work. Default 10. */
+    minCollapsePrefix: number;
+    /** Soft-wrap columns for the renderer; should match host cols. Default 100. */
+    cols: number;
+    /** Advance the collapse boundary in steps of this many messages so the rendered PNG stays
+     *  byte-identical for collapseChunk turns and keeps hitting Anthropic's prompt cache.
+     *  Set to 0 for a per-turn moving boundary. Default 50. */
+    collapseChunk: number;
+    /** Append-only freeze granularity, in messages. The collapse range is rendered
+     *  as independent image blocks on an ABSOLUTE grid anchored at protectedPrefix,
+     *  in steps of this many messages. Each completed chunk's bytes are fixed by its
+     *  message range alone, so old chunks stay byte-identical (cache_read forever) as
+     *  the conversation grows — only the newest partial chunk re-renders. Caller
+     *  cache_control marks force an extra split so a roaming breakpoint stays an
+     *  aligned, independently-cacheable image boundary. Set to 0 to render the whole
+     *  range as one paginated blob (legacy, non-append-only). Default 10. */
+    freezeChunk: number;
+    /** Leading messages to never collapse. Protects the slab-bearing first user message
+     *  (system-prompt + tool-docs images) so its cache_control anchor stays at the front
+     *  and isn't swept into the history image as [image] placeholders. Default 0. */
+    protectedPrefix: 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, inflating image count and shrinking
+     *  the savings. Glyph size is unchanged (cols stays the same) so legibility is
+     *  identical — it just removes the blank-row waste. `collapsedChars` still
+     *  reports the ORIGINAL transcript length. Default true. */
+    reflow: boolean;
+}
+export declare const HISTORY_DEFAULTS: HistoryCollapseOptions;
+/** Per-request telemetry surfaced back to TransformInfo. */
+export interface HistoryCollapseInfo {
+    /** Number of turns collapsed into the history image. */
+    collapsedTurns: number;
+    /** Total chars of text that went into the history image. */
+    collapsedChars: number;
+    /** Number of PNG image blocks emitted for the history (≥1 if collapsed). */
+    collapsedImages: number;
+    /** Total PNG bytes emitted. */
+    collapsedImageBytes: number;
+    /** Total pixel area (Σ width×height) — pairs with cache_create tokens for px/token regression. */
+    collapsedImagePixels: number;
+    /** Raw PNG bytes of each emitted history image, in order. Lets the caller register
+     *  them into the dashboard image ring (info.imagePngs) so colored history frames are
+     *  visible, not merely counted — every other image path already feeds the ring. */
+    collapsedPngs: Uint8Array[];
+    /** Per-image pixel dims, parallel to collapsedPngs. The dashboard ring reads
+     *  info.imageDims in lockstep with info.imagePngs, so these must be pushed together. */
+    collapsedImageDims: {
+        width: number;
+        height: number;
+    }[];
+    /** Ordinal (0-based, into the emitted history images) of the last byte-stable
+     *  history image — the carry-over cache anchor. The relocator pins the cache
+     *  breakpoint here so it survives window advances (#11). Undefined when history is
+     *  too short to have a fully grid-aligned chunk before collapseLen. */
+    carryOverImageOrdinal?: number;
+    /** Why we didn't collapse — populated only when no collapse happened. */
+    reason?: 'no_history' | 'prefix_too_short' | 'no_closed_prefix' | 'not_profitable' | 'render_empty';
+    /** Dropped codepoints from the history render, merged into the
+     *  transform-wide map by the caller. */
+    droppedChars: number;
+    droppedCodepoints: Map<number, number>;
+}
+/**
+ * Return the last index ≤ cutoffExclusive at which all tool_use_ids are matched
+ * by tool_results in [0..i]. Returns -1 if no closed boundary exists.
+ * Robust to interleaved/parallel tool calls via openSet tracking.
+ */
+export declare function findClosedPrefixBoundary(messages: Message[], cutoffExclusive: number): number;
+export declare function staleFreshnessHints(text: string): string;
+/**
+ * Linearise content blocks to a single string. Drops thinking blocks (only the
+ * most-recent assistant turn needs bit-perfect thinking, and it's in the live tail).
+ * Inline images collapse to [image] to avoid double-encoding.
+ */
+export declare function blocksToText(content: string | ContentBlock[]): string;
+/** Return the caller's cache_control marker on a message, if any block carries one.
+ *  Used to align freeze-chunk boundaries to roaming breakpoints so a marked segment
+ *  stays independently cacheable instead of being silently flattened into the image. */
+export declare function messageCacheControl(m: Message): CacheControl | undefined;
+/** Serialize messages [fromInclusive..upToExclusive) to a text blob with
+ *  `<role>…</role>` XML wrappers. Open+close tags bracket each turn so a misread
+ *  boundary self-corrects and the model attributes speakers reliably even off a
+ *  lossy image — bare `--- role ---` start-dividers let one role bleed into the
+ *  next when a divider is missed. */
+export declare function messagesToHistoryText(messages: Message[], upToExclusive: number, fromInclusive?: number): string;
+/** Like {@link messagesToHistoryText} but also returns the parallel slot string for
+ *  colorByRole: a width-identical copy where each `<role>` tag is replaced by its
+ *  role marker and the body is copied verbatim (slot 0). Role attribution is decided
+ *  HERE, where the message role is known — never re-parsed out of flattened text.
+ *  A tool_result block sits inside its user message and a tool_use block inside its
+ *  assistant message, so each is owned by the turn that carries it. */
+export declare function messagesToHistorySegments(messages: Message[], upToExclusive: number, fromInclusive?: number): {
+    text: string;
+    slotText: string;
+};
+/**
+ * Collapse the closed-prefix run into one synthetic user message with 1+ history images.
+ * Returns original messages unchanged on any no-collapse path (reason set in info).
+ * Image blocks are returned with NO cache_control — caller decides placement.
+ */
+export declare function collapseHistory(messages: Message[], isProfitable: ProfitableFn, opts?: Partial<HistoryCollapseOptions>): Promise<{
+    messages: Message[];
+    info: HistoryCollapseInfo;
+}>;
+//# sourceMappingURL=history.d.ts.map