leetcode-capture-helper 0.0.0-stage → 0.1.1

package/runtime/extension/shared/code-ledger.js

@@ -0,0 +1,333 @@
+// extension/shared/code-ledger.js - what code the tutor has already been shown, and
+// what to tell it next.
+//
+// The rules (Thomson's request):
+//   - A Run (the button or Ctrl+') is never sent to the tutor on its own. It
+//     is only recorded, as the newest code for its problem.
+//   - A Submit is sent automatically, but only when its code differs from
+//     what the tutor already holds.
+//   - A typed message carries the code only when it changed since the tutor
+//     last saw it, and then as a diff against that version, not the whole
+//     code again. The first time (or after a reset) the tutor holds nothing,
+//     so the full code goes once; a diff that would be nearly as long as the
+//     code itself is replaced by the full code too.
+//   - The active problem is whichever one the student last sent a message,
+//     Run or Submit from. Activity on a different problem resets the tutor:
+//     the old problem's entry here is dropped and no problem's code counts
+//     as held any more, because the tutor's context is wiped with it.
+//
+// "Held" code (the baseline every diff is against) only advances through
+// commit(), which the caller makes once the backend call succeeded, so a
+// failed call never makes the ledger believe the tutor saw code it did not.
+//
+// Pure JavaScript with no Node API (no fs, http, process or Buffer), so the
+// same module can later run inside the browser extension. All I/O stays in
+// companion.js.
+
+import { formatDiffBody } from './context-budget.js';
+
+// A backstop on remembered problems: a reset already drops the old problem,
+// so this only bounds the case where resets are turned off.
+export const DEFAULT_MAX_PROBLEMS = 20;
+// A diff longer than this share of the code it describes saves too little to
+// be worth the model applying it; the full code goes instead.
+export const FULL_CODE_RATIO = 0.8;
+// Unchanged lines shown around each change, so the tutor can place it.
+export const DIFF_CONTEXT_LINES = 2;
+// Upper bound on the diff's table for the changed region (see diffLines'
+// maxCells): about 2,000 by 2,000 changed lines. Past it the full code goes.
+export const MAX_DIFF_CELLS = 4_000_000;
+
+// What every stateless request labels the pinned current code with (see
+// formatPinnedCode).
+export const CURRENT_CODE_LABEL = "The student's current code";
+
+// Shown to the model in place of an older turn's full code, since every
+// request pins the current code (see context-budget.js's buildMessages).
+export const FULL_CODE_COMPACT_NOTE =
+  `(The student's full code was shown here. Their current code is pinned at the top of the conversation as "${CURRENT_CODE_LABEL}".)`;
+
+// Only a Submit is sent to the tutor by itself. Anything else, a Run or an
+// unknown trigger (the relay's /capture route accepts posts from any page),
+// is only recorded.
+export function sendsToTutor(trigger) {
+  return trigger === 'submit';
+}
+
+export function languageFenceHint(language) {
+  const known = {
+    python: 'python',
+    python3: 'python',
+    javascript: 'javascript',
+    typescript: 'typescript',
+    java: 'java',
+    'c++': 'cpp',
+    cpp: 'cpp',
+    c: 'c',
+    'c#': 'csharp',
+    go: 'go',
+    golang: 'go',
+    rust: 'rust',
+    kotlin: 'kotlin',
+    swift: 'swift',
+    ruby: 'ruby',
+    scala: 'scala',
+    php: 'php',
+  };
+  return known[String(language).toLowerCase()] || '';
+}
+
+function fenced(code, language) {
+  return `\`\`\`${languageFenceHint(language)}\n${code}\n\`\`\``;
+}
+
+function languageName(language) {
+  return language || 'unknown language';
+}
+
+export function createCodeLedger({ maxProblems = DEFAULT_MAX_PROBLEMS } = {}) {
+  // problemId -> { slug, context, latest, held }, least recently used first.
+  //   context: { title, slug, description } from the newest capture or snapshot
+  //   latest:  { code, language } the newest code seen from any source
+  //   held:    { code, language } what the tutor has been shown, or null
+  const problems = new Map();
+  let activeId = null;
+
+  function touch(problemId) {
+    let entry = problems.get(problemId);
+    if (entry) problems.delete(problemId);
+    else entry = { slug: null, context: null, latest: null, held: null };
+    problems.set(problemId, entry);
+    for (const id of problems.keys()) {
+      if (problems.size <= maxProblems) break;
+      if (id !== problemId && id !== activeId) problems.delete(id);
+    }
+    return entry;
+  }
+
+  return {
+    get activeProblemId() {
+      return activeId;
+    },
+
+    // Makes problemId the active problem. When another problem was active and
+    // resetOnSwitch is on, that problem is dropped and no code counts as held
+    // any more: the caller wipes the tutor's context to match. `dropped`
+    // names the old problem (and its slug, when it had one) so the caller can
+    // clear what else it keeps about it.
+    activate(problemId, { slug = null, resetOnSwitch = true } = {}) {
+      if (!problemId) return { switched: false, reset: false, previousId: activeId, dropped: null };
+      const previousId = activeId;
+      const switched = previousId !== null && previousId !== problemId;
+      let dropped = null;
+      activeId = problemId;
+      if (switched && resetOnSwitch) {
+        const old = problems.get(previousId);
+        problems.delete(previousId);
+        dropped = { problemId: previousId, slug: old ? old.slug : null };
+        for (const entry of problems.values()) entry.held = null;
+      }
+      const entry = touch(problemId);
+      if (slug) entry.slug = slug;
+      return { switched, reset: switched && resetOnSwitch, previousId, dropped };
+    },
+
+    // Records the newest code for a problem (a Run, a Submit, or the live
+    // editor read at send time). `context` is the problem statement that came
+    // with it; a later source without a description keeps the one known.
+    record(problemId, { code, language = null, slug = null, context = null } = {}) {
+      if (!problemId) return;
+      const entry = touch(problemId);
+      if (slug) entry.slug = slug;
+      if (typeof code === 'string') entry.latest = { code, language: language || null };
+      if (context) {
+        const description = context.description || (entry.context && entry.context.description) || null;
+        entry.context = { ...context, description };
+      }
+    },
+
+    latest(problemId) {
+      const entry = problems.get(problemId);
+      return entry ? entry.latest : null;
+    },
+
+    context(problemId) {
+      const entry = problems.get(problemId);
+      return entry ? entry.context : null;
+    },
+
+    held(problemId) {
+      const entry = problems.get(problemId);
+      return entry ? entry.held : null;
+    },
+
+    has(problemId) {
+      return problems.has(problemId);
+    },
+
+    get size() {
+      return problems.size;
+    },
+
+    // What the tutor needs to be told about this problem's code, without
+    // changing anything: `none` (no code known), `unchanged` (the tutor holds
+    // exactly this), `full` or `diff`. `current` defaults to the newest code
+    // recorded.
+    planUpdate(problemId, current = undefined) {
+      const entry = problems.get(problemId);
+      const code = current === undefined ? entry && entry.latest : current;
+      if (!code || typeof code.code !== 'string') return { kind: 'none' };
+      const held = entry ? entry.held : null;
+      const language = code.language || (held && held.language) || null;
+      if (held && held.code === code.code && (held.language || null) === language) {
+        return { kind: 'unchanged', code: code.code, language };
+      }
+      const full = { kind: 'full', code: code.code, language };
+      // A language switch replaces the whole solution, and a diff against
+      // code in another language reads as nonsense.
+      if (!held || (held.language || null) !== language) return full;
+      const diff = formatDiffBody(held.code, code.code, {
+        context: DIFF_CONTEXT_LINES,
+        lineNumbers: true,
+        maxCells: MAX_DIFF_CELLS,
+      });
+      if (!diff || diff.body.length > FULL_CODE_RATIO * code.code.length) return full;
+      return { kind: 'diff', code: code.code, language, diff: diff.body, added: diff.added, removed: diff.removed };
+    },
+
+    // The backend call that carried this code succeeded: the tutor holds it.
+    commit(problemId, { code, language = null }) {
+      if (!problemId || typeof code !== 'string') return;
+      touch(problemId).held = { code, language: language || null };
+    },
+
+    // The tutor's context was wiped some other way: it holds no code.
+    forgetHeld() {
+      for (const entry of problems.values()) entry.held = null;
+    },
+  };
+}
+
+// The code part of a message for a plan from planUpdate, or null when there
+// is nothing to show (`none` or `unchanged`). A `full` plan carries the code
+// (a resumed Claude session has no pinned copy); a `diff` the numbered diff,
+// which the pinned full code alone cannot show: what the student just changed.
+export function formatCodeUpdate(plan) {
+  if (plan.kind === 'full') {
+    return `The student's current code (${languageName(plan.language)}), in full:\n\n${fenced(plan.code, plan.language)}`;
+  }
+  if (plan.kind === 'diff') {
+    return (
+      `Changes to the student's code since the version you last saw ` +
+      `(${languageName(plan.language)}, +${plan.added}/-${plan.removed} lines; the line numbers are those of ` +
+      `the current code):\n\n` +
+      `\`\`\`diff\n${plan.diff}\n\`\`\``
+    );
+  }
+  return null;
+}
+
+// The block holding the student's current full code, which every request
+// carries (see context-budget.js's buildMessages, and ClaudeBackend's
+// session path), or null when no code is known. `code.stale` marks the last
+// version the tutor was shown, standing in when the editor could not be read.
+export function formatPinnedCode(code) {
+  if (!code || typeof code.code !== 'string' || code.inMessage) return null;
+  const language = languageName(code.language);
+  const header = code.stale
+    ? `${CURRENT_CODE_LABEL} (${language}), as last read: their editor could not be read for the newest ` +
+      'message, so this is the last version you were shown and it may be out of date.'
+    : `${CURRENT_CODE_LABEL} (${language}), exactly as it is now. Every code change shown in the conversation ` +
+      'is already applied here; reason about this version.';
+  return `${header}\n\n${fenced(code.code, code.language)}`;
+}
+
+// The code a turn's request carries: the code the plan sends (full, diff or
+// unchanged), else the last version the tutor was shown (marked stale when
+// the editor could not be read), else null. A `full` plan's message already
+// holds the whole code, so it is marked `inMessage` and not pinned a second
+// time on that request (formatPinnedCode); every later request pins it.
+export function currentCodeFor(plan, held, { codeUnavailable = false } = {}) {
+  if (plan && typeof plan.code === 'string' && (plan.kind === 'full' || plan.kind === 'diff' || plan.kind === 'unchanged')) {
+    return { code: plan.code, language: plan.language || null, stale: false, ...(plan.kind === 'full' ? { inMessage: true } : {}) };
+  }
+  if (held && typeof held.code === 'string') return { code: held.code, language: held.language || null, stale: Boolean(codeUnavailable) };
+  return null;
+}
+
+// A Submit: its header line, the code update (full or diff), then the
+// instruction for how to answer. `compactText` is what an older copy of this
+// turn becomes once its code is pinned instead: no full code, no instruction.
+export function buildSubmitMessage({ headerLine, plan, addendum = '' }) {
+  const update = formatCodeUpdate(plan);
+  const text = update ? `${headerLine}\n\n${update}${addendum}` : `${headerLine}${addendum}`;
+  let compactText = text;
+  if (plan.kind === 'full') compactText = `${headerLine}\n\n${FULL_CODE_COMPACT_NOTE}`;
+  else if (update) compactText = `${headerLine}\n\n${update}`;
+  return { text, compactText };
+}
+
+// A typed message: an optional preamble (which problem the student is on),
+// the code update when the code changed, then what they wrote. With neither,
+// the message goes exactly as typed.
+export function buildChatMessage({ text, plan = { kind: 'none' }, preamble = null }) {
+  const update = formatCodeUpdate(plan);
+  const parts = [];
+  const compactParts = [];
+  if (preamble) {
+    parts.push(preamble);
+    compactParts.push(preamble);
+  }
+  if (update) {
+    parts.push(update);
+    compactParts.push(plan.kind === 'full' ? FULL_CODE_COMPACT_NOTE : update);
+  }
+  if (parts.length === 0) return { text, compactText: text };
+  const message = update ? `The student's message:\n${text}` : text;
+  parts.push(message);
+  compactParts.push(message);
+  return { text: parts.join('\n\n'), compactText: compactParts.join('\n\n') };
+}
+
+// The notes a panel message leads with: the problem the student moved to,
+// and why their code is missing when the editor could not be read.
+export function chatPreamble({ previousId, problemId, codeUnavailable = false, hasHeld = false }) {
+  const notes = [];
+  if (problemId && previousId !== problemId) notes.push(`(The student is now working on the LeetCode problem "${problemId}".)`);
+  if (codeUnavailable) {
+    notes.push(
+      hasHeld
+        ? `(The student's editor could not be read, so their newest code is not included: "${CURRENT_CODE_LABEL}" is the last version you were shown and may be out of date.)`
+        : "(The student's editor could not be read, so their current code is not included.)"
+    );
+  }
+  return notes.length ? notes.join('\n') : null;
+}
+
+// Everything a typed message's turn needs, the same in both runtimes (the
+// companion and the extension's engine): the plan, the message, and the code
+// the request carries. `preamble` is a string, a function of { plan, hasHeld },
+// or null.
+export function prepareChatTurn(ledger, { text, problemId, preamble = null, codeUnavailable = false }) {
+  const plan = problemId && !codeUnavailable ? ledger.planUpdate(problemId) : { kind: 'none' };
+  const held = problemId ? ledger.held(problemId) : null;
+  const lead = typeof preamble === 'function' ? preamble({ plan, hasHeld: Boolean(held) }) : preamble;
+  const message = buildChatMessage({ text, plan, preamble: lead });
+  return {
+    plan,
+    message,
+    problemContext: (problemId && ledger.context(problemId)) || undefined,
+    currentCode: currentCodeFor(plan, held, { codeUnavailable }),
+  };
+}
+
+// The same for a Submit the ledger decided to send (plan `full` or `diff`).
+export function prepareSubmitTurn(ledger, { problemId, plan, headerLine, addendum = '', fallbackContext = null }) {
+  const message = buildSubmitMessage({ headerLine, plan, addendum });
+  return {
+    plan,
+    message,
+    problemContext: ledger.context(problemId) || fallbackContext || undefined,
+    currentCode: currentCodeFor(plan, ledger.held(problemId)),
+  };
+}

package/runtime/extension/shared/context-budget.js

@@ -0,0 +1,259 @@
+// extension/shared/context-budget.js - pure helpers for LocalBackend's context-
+// budget management: the pre-flight request-size estimate, the line diff
+// the tutor's code updates are built from (see code-ledger.js), and the
+// outgoing message list with the pinned description and code. Split out
+// from companion.js so this logic - deterministic, no I/O, no readline or
+// backend state - can be unit-tested directly, the same way
+// terminal-format.js and vault-summary.js already are, rather than only
+// reachable through a full companion.js subprocess. It uses no Node API, so
+// it can also run inside the browser extension. See companion.js's
+// LocalBackend class comment and the top-level AGENTS.md for the
+// live-confirmed failures this exists to address.
+
+// Cheap character-based token-count estimate, used only for the pre-flight
+// size check in LocalBackend.sendMessage (companion.js) - not a real
+// tokenizer, and not meant to be one. Calibrated against the real, locally-
+// running gemma4:26b model this project is configured for (not assumed):
+// four live /api/chat requests at 30/100/250/500 lines of realistic Python
+// code measured 4.28/4.13/4.01/3.93 characters per prompt token
+// respectively - converging toward ~3.9 as size grows, matching
+// data/companion-context-capacity-test's own finding (in the firstmate
+// repo) almost exactly. 3.9 is used here deliberately as the conservative
+// (lower) end of that measured range: since estimated tokens = length /
+// CHARS_PER_TOKEN_ESTIMATE, a smaller divisor yields a larger (safer, more
+// conservative - more likely to trigger the pre-flight refusal) estimate
+// for the same character count, and the measured ratio is lowest, i.e.
+// closest to 3.9, exactly in the large-capture danger zone this check
+// exists to catch - so this estimate is most accurate right where it
+// matters most.
+export const CHARS_PER_TOKEN_ESTIMATE = 3.9;
+
+export function estimateTokens(text) {
+  return Math.ceil((text || '').length / CHARS_PER_TOKEN_ESTIMATE);
+}
+
+export function estimateMessagesTokens(messages) {
+  return messages.reduce((sum, m) => sum + estimateTokens(m.content), 0);
+}
+
+// A simple LCS-based line diff (no external dependency - this project's own
+// "no deps" bar, see companion/'s own header comment). The common leading
+// and trailing lines are matched up front, so the quadratic LCS table only
+// covers the region that actually changed: a one-line edit in a 300-line
+// solution costs a tiny table, not a 300 by 300 one. Not meant to be a
+// byte-perfect unified diff, just a correct and compact list of operations.
+// `maxCells` bounds that table: past it this returns null instead of
+// allocating it (a rewrite of a very long file), and the caller sends the
+// whole code instead.
+export function diffLines(oldLines, newLines, { maxCells = Infinity } = {}) {
+  let prefix = 0;
+  while (prefix < oldLines.length && prefix < newLines.length && oldLines[prefix] === newLines[prefix]) prefix++;
+  let suffix = 0;
+  while (
+    suffix < oldLines.length - prefix &&
+    suffix < newLines.length - prefix &&
+    oldLines[oldLines.length - 1 - suffix] === newLines[newLines.length - 1 - suffix]
+  ) {
+    suffix++;
+  }
+  const oldMid = oldLines.slice(prefix, oldLines.length - suffix);
+  const newMid = newLines.slice(prefix, newLines.length - suffix);
+  const n = oldMid.length;
+  const m = newMid.length;
+  if ((n + 1) * (m + 1) > maxCells) return null;
+  const lcs = Array.from({ length: n + 1 }, () => new Int32Array(m + 1));
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      lcs[i][j] = oldMid[i] === newMid[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+    }
+  }
+  const ops = [];
+  for (let k = 0; k < prefix; k++) ops.push({ type: 'same', line: oldLines[k] });
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (oldMid[i] === newMid[j]) {
+      ops.push({ type: 'same', line: oldMid[i] });
+      i++;
+      j++;
+    } else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+      ops.push({ type: 'del', line: oldMid[i] });
+      i++;
+    } else {
+      ops.push({ type: 'add', line: newMid[j] });
+      j++;
+    }
+  }
+  while (i < n) {
+    ops.push({ type: 'del', line: oldMid[i] });
+    i++;
+  }
+  while (j < m) {
+    ops.push({ type: 'add', line: newMid[j] });
+    j++;
+  }
+  for (let k = oldLines.length - suffix; k < oldLines.length; k++) ops.push({ type: 'same', line: oldLines[k] });
+  return ops;
+}
+
+// Renders diffLines' ops as +/- lines with `context` unchanged lines around
+// each change, collapsing everything else to "...". With `lineNumbers`, every
+// unchanged or added line also carries its line number in the NEW code (a
+// removed line has none, it no longer exists there), so a reader holding the
+// old code can place each change without a unified diff's hunk headers.
+// Returns the rendered lines plus the added/removed counts, or null when
+// diffLines gave up (see its `maxCells`).
+export function formatDiffBody(oldCode, newCode, { context = 1, lineNumbers = false, maxCells } = {}) {
+  const ops = diffLines((oldCode || '').split('\n'), (newCode || '').split('\n'), { maxCells });
+  if (!ops) return null;
+  const keep = new Array(ops.length).fill(false);
+  ops.forEach((op, idx) => {
+    if (op.type === 'same') return;
+    for (let k = Math.max(0, idx - context); k <= Math.min(ops.length - 1, idx + context); k++) keep[k] = true;
+  });
+  const newLineCount = ops.filter((op) => op.type !== 'del').length;
+  const width = String(Math.max(1, newLineCount)).length;
+  const out = [];
+  let skipping = false;
+  let added = 0;
+  let removed = 0;
+  let newLineNo = 0;
+  ops.forEach((op, idx) => {
+    if (op.type !== 'del') newLineNo++;
+    if (op.type === 'add') added++;
+    if (op.type === 'del') removed++;
+    if (!keep[idx]) {
+      if (!skipping) {
+        out.push('...');
+        skipping = true;
+      }
+      return;
+    }
+    skipping = false;
+    const prefix = op.type === 'add' ? '+' : op.type === 'del' ? '-' : ' ';
+    if (lineNumbers) {
+      const number = op.type === 'del' ? ''.padStart(width) : String(newLineNo).padStart(width);
+      out.push(`${prefix} ${number} | ${op.line}`);
+    } else {
+      out.push(`${prefix} ${op.line}`);
+    }
+  });
+  return { body: out.join('\n'), added, removed };
+}
+
+// The compact +/- summary with 1 line of context, under a one-line header -
+// a full unified diff's hunk headers aren't worth the tokens here, the model
+// just needs to see what changed between two attempts.
+export function formatDiffSummary(oldCode, newCode) {
+  if (oldCode === newCode) return '(code unchanged from the previous attempt)';
+  const { body, added, removed } = formatDiffBody(oldCode, newCode);
+  return `Code changed from the previous attempt (+${added}/-${removed} lines):\n${body}`;
+}
+
+// Builds the actual outgoing messages array for a stateless request: the
+// leading system message, the pinned problem statement right after it (if
+// one is known), then the pinned code (the student's current full code, with
+// this turn's change already applied), then the summary of condensed older
+// exchanges if there is one (context-summary.js), then the rest of history.
+// Most stable first, so a server's prefix cache keeps as much as it can. An
+// older user turn with a `compactContent` (a Submit's answer instructions)
+// is sent as that while code is pinned; the turn just pushed for this
+// request is always last and always sent in full.
+//
+// Pinning is what lets condensing or dropping old exchanges
+// (context-summary.js) never lose the statement or the code: every request
+// carries both whole. Pure function of its inputs -
+// LocalBackend.buildMessages (companion.js) is a thin wrapper passing its
+// own fields through - so it can be unit-tested without a real backend.
+// `history` is never mutated.
+// The "earlier in this session" summary (context-summary.js) that stands in
+// for condensed older exchanges: its header, and the message it is sent as.
+export const SUMMARY_HEADER =
+  'Earlier in this session (a short summary of older exchanges that are no longer shown in full):';
+
+export function summaryContent(summary) {
+  return `${SUMMARY_HEADER}\n${summary}`;
+}
+
+export function buildMessages({ history, pinnedProblemContext, pinnedCode = null, summary = null }) {
+  const messages = [history[0]]; // the leading system message
+  if (pinnedProblemContext?.description) {
+    messages.push({
+      role: 'system',
+      content:
+        `Problem currently being discussed: ${pinnedProblemContext.title} ` +
+        `(${pinnedProblemContext.slug})\n\n${pinnedProblemContext.description}`,
+    });
+  }
+  if (pinnedCode && typeof pinnedCode.text === 'string') {
+    messages.push({ role: 'system', content: pinnedCode.text });
+  }
+  if (typeof summary === 'string' && summary) {
+    messages.push({ role: 'system', content: summaryContent(summary) });
+  }
+
+  const rest = history.slice(1);
+  const currentTurnIndex = rest.length - 1;
+  for (let i = 0; i < rest.length; i++) {
+    const msg = rest[i];
+    const compact =
+      Boolean(pinnedCode) && msg.role === 'user' && i !== currentTurnIndex && typeof msg.compactContent === 'string';
+    messages.push({ role: msg.role, content: compact ? msg.compactContent : msg.content });
+  }
+  return messages;
+}
+
+// The context window LocalBackend budgets against: the smallest of what is
+// configured (COMPANION_LOCAL_NUM_CTX, or a settings field later), what the
+// server reported when probed (local-server.js), and what a reply showed
+// the server really kept (LocalBackend's silent-truncation guard). Any of
+// the last two may be missing. Returns the window and where it came from,
+// so messages can say which one is in charge. The one place the window is
+// decided, so a new source (a settings field) only needs a new argument.
+export function resolveContextWindow({ configured, detected = null, observed = null }) {
+  let best = { tokens: configured, source: 'configured' };
+  if (detected && detected.tokens > 0 && detected.tokens < best.tokens) {
+    best = { tokens: detected.tokens, source: 'detected', from: detected.source };
+  }
+  if (observed && observed > 0 && observed < best.tokens) best = { tokens: observed, source: 'observed' };
+  return best;
+}
+
+// Fits one request to the prompt budget by dropping, the last resort behind
+// context-summary.js's fitWithSummary (which condenses instead whenever even
+// a small summary fits, and is what LocalBackend calls): `history` is
+// [system, user, assistant, ..., user] with the current message last. While
+// the request is over budget, the oldest whole user+assistant exchange is
+// dropped (never half of one, never the pinned statement or code, never the
+// current message). Returns the history to keep, the messages to send and
+// their estimate, how many exchanges went, and whether it fits. When even
+// the pinned parts plus the current message are over, `parts` gives each
+// one's estimate so the refusal can say what is too big. Pure: `history`
+// is never mutated.
+export function fitToBudget({ history, pinnedProblemContext = null, pinnedCode = null, budget }) {
+  let kept = history;
+  let droppedPairs = 0;
+  let messages = buildMessages({ history: kept, pinnedProblemContext, pinnedCode });
+  let estimatedTokens = estimateMessagesTokens(messages);
+  // kept is [system, (user, assistant)*, current]: an exchange is left to
+  // drop while there are at least four entries.
+  while (estimatedTokens > budget && kept.length >= 4 && kept[1].role === 'user' && kept[2].role === 'assistant') {
+    kept = [kept[0], ...kept.slice(3)];
+    droppedPairs += 1;
+    messages = buildMessages({ history: kept, pinnedProblemContext, pinnedCode });
+    estimatedTokens = estimateMessagesTokens(messages);
+  }
+  const fits = estimatedTokens <= budget;
+  const result = { history: kept, messages, estimatedTokens, droppedPairs, fits };
+  if (!fits) {
+    const current = kept[kept.length - 1];
+    const problemTokens = pinnedProblemContext?.description ? estimateTokens(messages[1].content) : 0;
+    result.parts = {
+      systemPrompt: estimateTokens(kept[0].content),
+      problem: problemTokens,
+      code: pinnedCode && typeof pinnedCode.text === 'string' ? estimateTokens(pinnedCode.text) : 0,
+      message: estimateTokens(current.content),
+    };
+  }
+  return result;
+}