@brunobracaioli/aibrain 0.1.0-beta.1 → 0.3.0-beta.13

package/dist/assets/claude/hooks/provider-window.js

@@ -0,0 +1,263 @@
+import { preflightProviderState } from './state-fitting.mjs';
+export const PROVIDER_WINDOW_MAX_PAIRS = 200;
+export const PROVIDER_WINDOW_MAX_MESSAGES = 1_000;
+export const PROVIDER_WINDOW_MAX_REFERENCES = 200;
+export const PROVIDER_WINDOW_MAX_REQUEST_BYTES = 512 * 1024;
+export const PROVIDER_WINDOW_REQUEST_HEADROOM_BYTES = 16 * 1024;
+export const PROVIDER_WINDOW_MAX_SEARCH_ATTEMPTS = 12;
+export const PROVIDER_WINDOW_MAX_STATE_TOKENS = 25_000;
+export const PROVIDER_WINDOW_MAX_REQUEST_TOKENS = 30_000;
+export const PROVIDER_WINDOW_MAX_RESERVED_TOKENS = 120_000;
+export const PROVIDER_WINDOW_OUTPUT_TOKEN_ALLOWANCE = 4_000;
+function utf8Bytes(value) {
+    return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+}
+function anchorMessageIds(messages, preserveRecentMessages) {
+    return new Set(messages
+        .slice(0, 1)
+        .concat(messages.slice(Math.max(0, messages.length - preserveRecentMessages)))
+        .map((message) => message.id));
+}
+function pairIdsFromMessages(messages) {
+    return new Set(messages.flatMap((message) => [...message.callIds, ...message.resultIds]));
+}
+function compareEligible(a, b) {
+    return b.resultChars - a.resultChars || a.callMessage - b.callMessage || a.id.localeCompare(b.id);
+}
+function uniqueMarkerId(messages) {
+    const ids = new Set(messages.map((message) => message.id));
+    let candidate = 'provider-window-omitted';
+    let sequence = 0;
+    while (ids.has(candidate))
+        candidate = `provider-window-omitted-${++sequence}`;
+    return candidate;
+}
+function abbreviatedText(text, limit) {
+    if (text.length <= limit)
+        return text;
+    if (limit <= 0)
+        return `[historical message omitted; ${text.length} chars]`;
+    const head = Math.max(1, Math.floor(limit * 0.65));
+    const tail = Math.max(1, limit - head);
+    return `${text.slice(0, head)}…[omitted ${text.length - head - tail} chars]…${text.slice(-tail)}`;
+}
+function boundedMessages(messages, selectedIds, anchorIds, maxMessages) {
+    const filtered = messages.map((message) => ({
+        ...message,
+        callIds: message.callIds.filter((id) => selectedIds.has(id)),
+        resultIds: message.resultIds.filter((id) => selectedIds.has(id)),
+    }));
+    if (filtered.length <= maxMessages)
+        return filtered;
+    const retained = filtered.filter((message) => anchorIds.has(message.id) || message.callIds.length > 0 || message.resultIds.length > 0);
+    if (retained.length > maxMessages)
+        return null;
+    const output = [];
+    const usedIds = new Set(filtered.map((message) => message.id));
+    let markerSequence = 0;
+    let omitted = 0;
+    let markerPending = false;
+    const flush = () => {
+        if (!markerPending)
+            return;
+        let markerId = uniqueMarkerId(output);
+        while (usedIds.has(markerId))
+            markerId = `provider-window-omitted-${++markerSequence}`;
+        usedIds.add(markerId);
+        output.push({
+            id: markerId,
+            role: 'user',
+            text: `[${omitted} historical messages omitted from provider window]`,
+            callIds: [],
+            resultIds: [],
+        });
+        omitted = 0;
+        markerPending = false;
+    };
+    for (const message of filtered) {
+        if (anchorIds.has(message.id) || message.callIds.length > 0 || message.resultIds.length > 0) {
+            flush();
+            output.push(message);
+        }
+        else {
+            omitted += 1;
+            markerPending = true;
+        }
+    }
+    flush();
+    return output.length <= maxMessages ? output : null;
+}
+function transportMessages(messages, anchorIds, textLimit) {
+    if (textLimit === null)
+        return messages;
+    return messages.map((message) => anchorIds.has(message.id)
+        ? message
+        : { ...message, text: abbreviatedText(message.text, textLimit) });
+}
+function toWireProjection(input, selectedPairs, messages) {
+    return {
+        goal: input.goal,
+        messages: messages.map((message) => ({
+            id: message.id,
+            role: message.role,
+            text: message.text,
+            call_ids: [...message.callIds],
+            result_ids: [...message.resultIds],
+        })),
+        pairs: selectedPairs.map((pair) => ({
+            id: pair.id,
+            tool: pair.tool,
+            input_text: pair.inputText,
+            result_chars: pair.resultChars,
+            result_is_error: pair.resultIsError,
+            eligibility: pair.protectedPair ? 'protected' : pair.eligibility,
+            pin_reasons: [...pair.pinReasons],
+        })),
+        protected_item_count: input.protectedItemCount,
+    };
+}
+function toFitProjection(input, selectedPairs, messages) {
+    return {
+        goal: input.goal,
+        protectedItemCount: input.protectedItemCount,
+        messages,
+        pairs: selectedPairs,
+    };
+}
+function candidate(input, rankedEligible, mandatoryIds, count, options, fit) {
+    const selectedIds = new Set(mandatoryIds);
+    rankedEligible.slice(0, count).forEach((pair) => selectedIds.add(pair.id));
+    const selectedPairs = input.pairs.filter((pair) => selectedIds.has(pair.id));
+    if (selectedPairs.length > options.maxPairs)
+        return null;
+    const anchorIds = anchorMessageIds(input.messages, options.preserveRecentMessages);
+    const messages = boundedMessages(input.messages, selectedIds, anchorIds, options.maxMessages);
+    if (messages === null)
+        return null;
+    if (messages.some((message) => message.callIds.length > options.maxReferencesPerMessage ||
+        message.resultIds.length > options.maxReferencesPerMessage))
+        return null;
+    const eligible = selectedPairs.filter((pair) => !pair.protectedPair);
+    if (count === 0 && eligible.length === 0)
+        return null;
+    const textLimits = [null, 4_096, 1_024, 256, 64, 0];
+    for (const textLimit of textLimits) {
+        const transportReadyMessages = transportMessages(messages, anchorIds, textLimit);
+        const wire = toWireProjection(input, selectedPairs, transportReadyMessages);
+        const requestBytes = utf8Bytes({ projection: wire });
+        if (requestBytes + options.requestHeadroomBytes > options.maxRequestBytes)
+            continue;
+        const preflight = fit(toFitProjection(input, selectedPairs, transportReadyMessages), eligible, options);
+        if (!preflight.fits)
+            return null;
+        const maxBatches = options.maxBatchesPerOperation ?? 4;
+        if (!Number.isSafeInteger(maxBatches) || maxBatches < 1 || preflight.batchCount > maxBatches)
+            return null;
+        const outputAllowance = options.outputTokenAllowance ?? PROVIDER_WINDOW_OUTPUT_TOKEN_ALLOWANCE;
+        if (!Number.isSafeInteger(outputAllowance) || outputAllowance < 0)
+            return null;
+        const estimatedReservationTokens = ((preflight.requestTokens ?? Number.POSITIVE_INFINITY) + outputAllowance) *
+            preflight.batchCount;
+        if (estimatedReservationTokens > options.maxReservedTokens)
+            return null;
+        return {
+            ok: true,
+            projection: wire,
+            pairs: selectedPairs,
+            deferredPairs: input.pairs.filter((pair) => !selectedIds.has(pair.id)),
+            preflight: { ...preflight, requestBytes, estimatedReservationTokens },
+            attempts: 0,
+            anchorPairCount: mandatoryIds.size,
+            selectedEligibleCount: eligible.length,
+        };
+    }
+    return null;
+}
+export function prepareProviderWindow(input, options, fit = preflightProviderState) {
+    const limits = {
+        maxPairs: Math.min(options.maxPairs ?? PROVIDER_WINDOW_MAX_PAIRS, PROVIDER_WINDOW_MAX_PAIRS),
+        maxMessages: Math.min(options.maxMessages ?? PROVIDER_WINDOW_MAX_MESSAGES, PROVIDER_WINDOW_MAX_MESSAGES),
+        maxReferencesPerMessage: Math.min(options.maxReferencesPerMessage ?? PROVIDER_WINDOW_MAX_REFERENCES, PROVIDER_WINDOW_MAX_REFERENCES),
+        maxRequestBytes: Math.min(options.maxRequestBytes ?? PROVIDER_WINDOW_MAX_REQUEST_BYTES, PROVIDER_WINDOW_MAX_REQUEST_BYTES),
+        requestHeadroomBytes: Math.max(options.requestHeadroomBytes ?? PROVIDER_WINDOW_REQUEST_HEADROOM_BYTES, PROVIDER_WINDOW_REQUEST_HEADROOM_BYTES),
+        maxReservedTokens: Math.min(options.maxReservedTokens ?? PROVIDER_WINDOW_MAX_RESERVED_TOKENS, PROVIDER_WINDOW_MAX_RESERVED_TOKENS),
+    };
+    const fitOptions = {
+        ...options,
+        preserveRecentMessages: Math.min(Math.max(1, options.preserveRecentMessages), limits.maxMessages),
+        maxStateTokens: Math.min(options.maxStateTokens, PROVIDER_WINDOW_MAX_STATE_TOKENS),
+        maxRequestTokens: Math.min(options.maxRequestTokens, PROVIDER_WINDOW_MAX_REQUEST_TOKENS),
+        maxBatchesPerOperation: Math.min(Math.max(1, options.maxBatchesPerOperation ?? 4), 4),
+        outputTokenAllowance: Math.min(Math.max(0, options.outputTokenAllowance ?? PROVIDER_WINDOW_OUTPUT_TOKEN_ALLOWANCE), PROVIDER_WINDOW_OUTPUT_TOKEN_ALLOWANCE),
+    };
+    const anchors = anchorMessageIds(input.messages, fitOptions.preserveRecentMessages);
+    const mandatoryIds = pairIdsFromMessages(input.messages.filter((message) => anchors.has(message.id)));
+    if (mandatoryIds.size > limits.maxPairs)
+        return {
+            ok: false,
+            reason: 'anchor_overflow',
+            attempts: 0,
+            anchorPairCount: mandatoryIds.size,
+        };
+    const rankedEligible = input.pairs
+        .filter((pair) => !pair.protectedPair && !mandatoryIds.has(pair.id))
+        .sort(compareEligible);
+    const mandatoryEligibleCount = input.pairs.filter((pair) => mandatoryIds.has(pair.id) && !pair.protectedPair).length;
+    if (rankedEligible.length === 0 && mandatoryEligibleCount === 0)
+        return {
+            ok: false,
+            reason: 'no_feasible_window',
+            attempts: 0,
+            anchorPairCount: mandatoryIds.size,
+        };
+    const maxCount = Math.min(rankedEligible.length, limits.maxPairs - mandatoryIds.size);
+    let low = mandatoryEligibleCount > 0 ? 0 : 1;
+    let high = maxCount;
+    let best = null;
+    let bestCount = 0;
+    let attempts = 0;
+    while (low <= high && attempts < PROVIDER_WINDOW_MAX_SEARCH_ATTEMPTS) {
+        const count = Math.floor((low + high) / 2);
+        const result = candidate(input, rankedEligible, mandatoryIds, count, {
+            ...limits,
+            preserveRecentMessages: fitOptions.preserveRecentMessages,
+            maxStateTokens: fitOptions.maxStateTokens,
+            maxRequestTokens: fitOptions.maxRequestTokens,
+            maxReservedTokens: limits.maxReservedTokens,
+            maxBatchesPerOperation: fitOptions.maxBatchesPerOperation,
+            outputTokenAllowance: fitOptions.outputTokenAllowance,
+        }, fit);
+        attempts += 1;
+        if (result !== null) {
+            best = { ...result, attempts };
+            bestCount = count;
+            low = count + 1;
+        }
+        else
+            high = count - 1;
+    }
+    if (best === null)
+        return {
+            ok: false,
+            reason: 'no_feasible_window',
+            attempts,
+            anchorPairCount: mandatoryIds.size,
+        };
+    const final = candidate(input, rankedEligible, mandatoryIds, bestCount, {
+        ...limits,
+        preserveRecentMessages: fitOptions.preserveRecentMessages,
+        maxStateTokens: fitOptions.maxStateTokens,
+        maxRequestTokens: fitOptions.maxRequestTokens,
+        maxReservedTokens: limits.maxReservedTokens,
+        maxBatchesPerOperation: fitOptions.maxBatchesPerOperation,
+        outputTokenAllowance: fitOptions.outputTokenAllowance,
+    }, fit);
+    if (final === null)
+        return {
+            ok: false,
+            reason: 'no_feasible_window',
+            attempts: attempts + 1,
+            anchorPairCount: mandatoryIds.size,
+        };
+    return { ...final, attempts: attempts + 1 };
+}

package/dist/assets/claude/hooks/state-fitting.d.mts

@@ -0,0 +1,47 @@
+export type ProviderFitPreflightReason = 'fits' | 'budget_exceeded';
+
+export interface ProviderFitPreflight {
+  readonly fits: boolean;
+  readonly reason: ProviderFitPreflightReason;
+  readonly stage: string | null;
+  readonly stateTokens: number | null;
+  readonly requestTokens: number | null;
+  readonly batchCount: number;
+}
+
+export interface ProviderFitProjectionMessage {
+  readonly id: string;
+  readonly role: 'user' | 'assistant';
+  readonly text: string;
+  readonly callIds: readonly string[];
+  readonly resultIds: readonly string[];
+}
+
+export interface ProviderFitProjectionPair {
+  readonly id: string;
+  readonly tool: string;
+  readonly inputText: string;
+  readonly resultChars: number;
+  readonly resultIsError: boolean;
+  readonly eligibility: 'reproducible_read' | 'compatible_tool' | 'protected';
+  readonly pinReasons: readonly string[];
+}
+
+export interface ProviderFitProjection {
+  readonly goal: string;
+  readonly messages: readonly ProviderFitProjectionMessage[];
+  readonly pairs: readonly ProviderFitProjectionPair[];
+  readonly protectedItemCount: number;
+}
+
+export interface ProviderFitOptions {
+  readonly preserveRecentMessages: number;
+  readonly maxStateTokens: number;
+  readonly maxRequestTokens: number;
+}
+
+export function preflightProviderState(
+  projection: ProviderFitProjection,
+  eligible: readonly ProviderFitProjectionPair[],
+  options: ProviderFitOptions,
+): ProviderFitPreflight;

package/dist/assets/claude/hooks/state-fitting.mjs

@@ -0,0 +1,324 @@
+export const UTF8_ESTIMATOR_VERSION = 'utf8-bytes-v1';
+export const FIT_OVERHEAD_TOKENS = 256;
+export const FIT_MAX_BATCHES = 4;
+const textEncoder = typeof TextEncoder === 'function' ? new TextEncoder() : undefined;
+function utf8ByteLength(value) {
+  if (textEncoder !== undefined) return textEncoder.encode(value).byteLength;
+  const buffer = globalThis.Buffer;
+  if (buffer !== undefined) return buffer.byteLength(value, 'utf8');
+  throw new Error('utf8_encoder_unavailable');
+}
+export function estimateUtf8Tokens(value) {
+  return utf8ByteLength(JSON.stringify(value));
+}
+export function freezeProviderState(value) {
+  if (typeof value === 'object' && value !== null) {
+    Object.freeze(value);
+    for (const nested of Object.values(value)) freezeProviderState(nested);
+  }
+  return value;
+}
+function marker(text, head, tail = head) {
+  const codePoints = Array.from(text);
+  if (codePoints.length <= head + tail + 32) return text;
+  return `${codePoints.slice(0, head).join('')}…[omitted ${codePoints.length - head - tail} chars]…${codePoints.slice(-tail).join('')}`;
+}
+function takeCodePoints(text, count) {
+  return Array.from(text).slice(0, count).join('');
+}
+function codePointLength(text) {
+  return Array.from(text).length;
+}
+function stateFor(
+  projection,
+  pairs,
+  messages = projection.messages,
+  compactIds = new Set(),
+  omittedProtectedPairCount = 0,
+) {
+  return freezeProviderState({
+    goal: projection.goal,
+    messages: messages.map((message) => ({
+      id: message.id,
+      role: message.role,
+      text: message.text,
+      call_ids: [...message.callIds],
+      result_ids: [...message.resultIds],
+    })),
+    pairs: pairs.map((pair) =>
+      compactIds.has(pair.id)
+        ? {
+            id: pair.id,
+            compact_record: `${pair.id}|${pair.tool}|${takeCodePoints(pair.inputText, 12)}|result_chars=${pair.resultChars}|error=${pair.resultIsError}`,
+          }
+        : {
+            id: pair.id,
+            tool: pair.tool,
+            input_text: pair.inputText,
+            result_chars: pair.resultChars,
+            result_is_error: pair.resultIsError,
+          },
+    ),
+    protected_item_count: projection.protectedItemCount,
+    ...(omittedProtectedPairCount > 0
+      ? { omitted_protected_pair_count: omittedProtectedPairCount }
+      : {}),
+  });
+}
+export function compactionQuestions(pairs) {
+  return Object.fromEntries(
+    pairs.flatMap((pair) => [
+      [
+        `call_${pair.id}`,
+        {
+          type: 'noul',
+          instructions: `Should the call occurrence and input for pair ${pair.id} (${pair.tool}) remain useful for continuing the approved goal? Answer yes only when retaining the call is needed.`,
+        },
+      ],
+      [
+        `result_${pair.id}`,
+        {
+          type: 'noul',
+          instructions: `Should the full result for pair ${pair.id} (${pair.resultChars} characters) remain useful for continuing the approved goal? Answer yes only when the result itself is needed.`,
+        },
+      ],
+    ]),
+  );
+}
+export function estimateCompactionQuestions(pairs) {
+  return estimateUtf8Tokens(compactionQuestions(pairs));
+}
+function makeBatches(eligible, stateTokens, maxRequestTokens) {
+  const available = maxRequestTokens - stateTokens - FIT_OVERHEAD_TOKENS;
+  if (available <= 0) return null;
+  const batches = [];
+  let current = [];
+  let currentTokens = 0;
+  for (const pair of eligible) {
+    const pairTokens = estimateCompactionQuestions([pair]);
+    if (pairTokens > available) return null;
+    if (current.length > 0 && currentTokens + pairTokens > available) {
+      batches.push(current);
+      current = [];
+      currentTokens = 0;
+    }
+    current.push(pair);
+    currentTokens += pairTokens;
+  }
+  if (current.length > 0) batches.push(current);
+  if (batches.length > FIT_MAX_BATCHES) return null;
+  return {
+    batches,
+    requestTokens: batches.reduce(
+      (max, batch) =>
+        Math.max(max, stateTokens + FIT_OVERHEAD_TOKENS + estimateCompactionQuestions(batch)),
+      0,
+    ),
+  };
+}
+function isPinnedMessage(projection, messageIndex, recent, protectedIds, pinnedMessageIds) {
+  if (pinnedMessageIds.has(projection.messages[messageIndex]?.id ?? '')) return true;
+  return (
+    projection.messages[messageIndex]?.callIds.some((id) => protectedIds.has(id)) === true ||
+    projection.messages[messageIndex]?.resultIds.some((id) => protectedIds.has(id)) === true
+  );
+}
+function stageProjection(projection, eligibleIds, recent, stage, pinnedMessageIds) {
+  const protectedIds = new Set(
+    projection.pairs.filter((pair) => !eligibleIds.has(pair.id)).map((pair) => pair.id),
+  );
+  const pairs = projection.pairs.map((pair) => {
+    if (!eligibleIds.has(pair.id)) return pair;
+    if (stage === 'inputs_1000')
+      return { ...pair, inputText: takeCodePoints(pair.inputText, 1_000) };
+    if (stage === 'inputs_200') return { ...pair, inputText: takeCodePoints(pair.inputText, 200) };
+    if (stage === 'inputs_60') return { ...pair, inputText: takeCodePoints(pair.inputText, 60) };
+    if (stage === 'text_head_tail') return { ...pair, inputText: marker(pair.inputText, 30, 30) };
+    if (stage === 'text_omitted')
+      return codePointLength(pair.inputText) > 60
+        ? { ...pair, inputText: `[input omitted; ${codePointLength(pair.inputText)} chars]` }
+        : pair;
+    if (stage === 'compact_calls')
+      return { ...pair, inputText: `${pair.tool}(${marker(pair.inputText, 24, 12)})` };
+    return pair;
+  });
+  let messages = projection.messages;
+  if (stage === 'text_head_tail') {
+    messages = projection.messages.map((message, index) =>
+      isPinnedMessage(projection, index, recent, protectedIds, pinnedMessageIds)
+        ? message
+        : { ...message, text: marker(message.text, 80, 40) },
+    );
+  } else if (stage === 'text_omitted') {
+    messages = projection.messages.map((message, index) =>
+      isPinnedMessage(projection, index, recent, protectedIds, pinnedMessageIds)
+        ? message
+        : codePointLength(message.text) > 120
+          ? { ...message, text: `[message omitted; ${codePointLength(message.text)} chars]` }
+          : message,
+    );
+  } else if (stage === 'compact_calls') {
+    messages = projection.messages.map((message, index) =>
+      // At this stage pair identity and question binding live in `pairs`. Keep
+      // protected message wiring available while abbreviating only its text.
+      // A later fitting stage folds this wiring only if the complete state still
+      // cannot fit, so ordinary histories retain more useful provider context.
+      isPinnedMessage(projection, index, recent, protectedIds, pinnedMessageIds)
+        ? message
+        : {
+            ...message,
+            text: `call:${message.callIds.join(',')};result:${message.resultIds.join(',')}`,
+          },
+    );
+  } else if (stage === 'callless_omitted') {
+    messages = projection.messages.filter(
+      (message, index) =>
+        isPinnedMessage(projection, index, recent, protectedIds, pinnedMessageIds) ||
+        message.callIds.length > 0 ||
+        message.resultIds.length > 0,
+    );
+  } else if (stage === 'runs_folded') {
+    const folded = [];
+    const usedIds = new Set(projection.messages.map((message) => message.id));
+    let markerSequence = 0;
+    let omittedRun;
+    let omittedCount = 0;
+    const flushOmitted = () => {
+      if (omittedRun === undefined) return;
+      let id = 'provider-history-omitted';
+      while (usedIds.has(id)) id = `provider-history-omitted-${++markerSequence}`;
+      usedIds.add(id);
+      folded.push({
+        id,
+        role: omittedRun.role,
+        text: `[${omittedCount} historical messages omitted from provider metadata]`,
+        callIds: [],
+        resultIds: [],
+      });
+      omittedRun = undefined;
+      omittedCount = 0;
+    };
+    for (let index = 0; index < projection.messages.length; index += 1) {
+      const message = projection.messages[index];
+      if (message === undefined) continue;
+      if (pinnedMessageIds.has(message.id)) {
+        flushOmitted();
+        folded.push(message);
+      } else {
+        omittedRun ??= message;
+        omittedCount += 1;
+      }
+    }
+    flushOmitted();
+    messages = folded;
+  }
+  return { pairs, messages };
+}
+export function fitProviderState(projection, eligible, options) {
+  const beforeState = stateFor(projection, projection.pairs);
+  const beforeTokens = estimateUtf8Tokens(beforeState);
+  const eligibleIds = new Set(eligible.map((pair) => pair.id));
+  const pinnedMessageIds = new Set(
+    projection.messages
+      .slice(0, 1)
+      .concat(
+        projection.messages.slice(
+          Math.max(0, projection.messages.length - options.preserveRecentMessages),
+        ),
+      )
+      .map((message) => message.id),
+  );
+  const stages = [
+    'original',
+    'inputs_1000',
+    'inputs_200',
+    'inputs_60',
+    'text_head_tail',
+    'text_omitted',
+    'compact_calls',
+    'callless_omitted',
+    'runs_folded',
+  ];
+  let current = { pairs: projection.pairs, messages: projection.messages };
+  for (const [stageIndex, stage] of stages.entries()) {
+    if (stage !== 'original')
+      current = stageProjection(
+        { ...projection, pairs: current.pairs, messages: current.messages },
+        eligibleIds,
+        options.preserveRecentMessages,
+        stage,
+        pinnedMessageIds,
+      );
+    let transformed = current;
+    let omittedProtectedPairCount = 0;
+    if (stage === 'runs_folded') {
+      const retainedPairIds = new Set(
+        transformed.messages.flatMap((message) => [...message.callIds, ...message.resultIds]),
+      );
+      const retainedPairs = transformed.pairs.filter(
+        (pair) => eligibleIds.has(pair.id) || retainedPairIds.has(pair.id),
+      );
+      omittedProtectedPairCount = transformed.pairs.length - retainedPairs.length;
+      transformed = { ...transformed, pairs: retainedPairs };
+    }
+    // Once we reach the explicit compact-calls stage, abbreviate pair metadata
+    // while retaining identity, tool, size and outcome. Eligible inputs have
+    // already passed through bounded input stages, and the compact record keeps
+    // a short prefix for the provider's final question context.
+    const compactIds =
+      stageIndex >= stages.indexOf('compact_calls')
+        ? new Set(projection.pairs.map((pair) => pair.id))
+        : new Set();
+    const state = stateFor(
+      projection,
+      transformed.pairs,
+      transformed.messages,
+      compactIds,
+      omittedProtectedPairCount,
+    );
+    const stateTokens = estimateUtf8Tokens(state);
+    if (stateTokens > options.maxStateTokens) continue;
+    const packed = makeBatches(eligible, stateTokens, options.maxRequestTokens);
+    if (packed === null) continue;
+    return {
+      state,
+      fitting: {
+        version: 'state-fit-v1',
+        stage,
+        estimator: UTF8_ESTIMATOR_VERSION,
+        beforeEstimatedStateTokens: beforeTokens,
+        afterEstimatedStateTokens: stateTokens,
+      },
+      batches: packed.batches,
+      stateTokens,
+      requestTokens: packed.requestTokens,
+    };
+  }
+  throw new Error('state_fit_budget_exceeded');
+}
+/**
+ * Narrow, side-effect-free contract for the Claude provider-window planner.
+ * It intentionally does not expose the prepared provider state or transcript.
+ */
+export function preflightProviderState(projection, eligible, options) {
+  try {
+    const fitted = fitProviderState(projection, eligible, options);
+    return {
+      fits: true,
+      reason: 'fits',
+      stage: fitted.fitting.stage,
+      stateTokens: fitted.stateTokens,
+      requestTokens: fitted.requestTokens,
+      batchCount: fitted.batches.length,
+    };
+  } catch {
+    return {
+      fits: false,
+      reason: 'budget_exceeded',
+      stage: null,
+      stateTokens: null,
+      requestTokens: null,
+      batchCount: 0,
+    };
+  }
+}