@seanhogg/builderforce-memory 2026.10.24 → 2026.10.26

package/src/working/summary.ts

@@ -0,0 +1,113 @@
+/**
+ * The transcript summarizer — the ONE prompt every fold, hand-off note and chat
+ * consolidation compresses a conversation with. The model call is the host's
+ * ({@link SummaryCompletion}); this module owns what is asked and how the transcript is
+ * rendered for it, so a compaction note, a hand-off note and a "Consolidate" summary read
+ * the same everywhere.
+ */
+
+import { transcriptTokens, type TranscriptMessage } from './transcript.js';
+
+/** The summarizer's instructions. */
+export const TRANSCRIPT_SUMMARY_PROMPT =
+  'You compress an in-progress AI agent transcript into a concise MEMORY the agent keeps working from. Capture: the CURRENT outstanding instruction from the user (the most recent user message is authoritative — earlier requests it supersedes are history, not the active task), concrete facts/answers discovered, tool results that matter (ids, paths, values), decisions made, and what still remains to do. Keep every file path, symbol name and line number the remaining work depends on, with the specific facts learned from each file — the agent no longer sees those results, so what you leave out it must read again. Be information-dense; drop pleasantries. No preamble.';
+
+/**
+ * The note's output ceiling. A compaction note is a UTILITY completion: a bounded answer
+ * with no thinking. ~2.5k tokens: the note is the agent's only record of every file it
+ * folds (paths, symbols, line numbers), and 1.2k was too little to carry them.
+ */
+export const TRANSCRIPT_SUMMARY_MAX_TOKENS = 2_500;
+
+/**
+ * The most transcript one summarizer call reads (~tokens). A longer input — a whole long
+ * chat on "Consolidate", a first fold over a big seeded history — is summarized in
+ * CHUNKS of this size, each folded onto the note so far, so no single call can overrun
+ * a model's window.
+ */
+export const TRANSCRIPT_SUMMARY_INPUT_TOKENS = 48_000;
+
+/** One no-tools, no-reasoning completion — the host's model call. Resolves the text. */
+export type SummaryCompletion = (request: {
+  system: string;
+  user: string;
+  maxTokens: number;
+  signal?: AbortSignal;
+}) => Promise<string | null | undefined>;
+
+interface NamedToolCall {
+  function?: { name?: unknown };
+}
+
+/** Render a slice of the transcript to the compact text the summarizer compresses. */
+export function renderForSummary(msgs: readonly TranscriptMessage[]): string {
+  return msgs
+    .map((m) => {
+      const content = typeof m.content === 'string' ? m.content : JSON.stringify(m.content ?? '');
+      const calls = Array.isArray(m.tool_calls) && m.tool_calls.length > 0
+        ? ` [called: ${(m.tool_calls as NamedToolCall[]).map((t) => t.function?.name).filter((n): n is string => typeof n === 'string' && n.length > 0).join(', ')}]`
+        : '';
+      return `${m.role}${calls}: ${content}`;
+    })
+    .join('\n\n');
+}
+
+/**
+ * Split a transcript into consecutive chunks of at most `budget` tokens. A single message
+ * larger than the budget is a chunk of its own (its text is clipped when rendered).
+ */
+export function summaryChunks(msgs: readonly TranscriptMessage[], budget = TRANSCRIPT_SUMMARY_INPUT_TOKENS): TranscriptMessage[][] {
+  const chunks: TranscriptMessage[][] = [];
+  let chunk: TranscriptMessage[] = [];
+  let used = 0;
+  for (const m of msgs) {
+    const cost = transcriptTokens([m]);
+    if (chunk.length > 0 && used + cost > budget) {
+      chunks.push(chunk);
+      chunk = [];
+      used = 0;
+    }
+    chunk.push(m);
+    used += cost;
+  }
+  if (chunk.length > 0) chunks.push(chunk);
+  return chunks;
+}
+
+/** ~4 characters a token: the rendered text one call may carry. */
+const clip = (text: string, budget: number) => {
+  const max = budget * 4;
+  return text.length > max ? `${text.slice(0, max)}\n[…clipped]` : text;
+};
+
+/**
+ * Compress `msgs` into a memory note — in one call, or chunk by chunk with each chunk
+ * folded onto the note so far when the transcript is longer than one call may read. Null
+ * on any failure or an empty answer, so the caller falls back (drop-oldest, elision,
+ * "nothing to consolidate").
+ */
+export async function summarizeTranscript(
+  complete: SummaryCompletion,
+  msgs: readonly TranscriptMessage[],
+  signal?: AbortSignal,
+  budget = TRANSCRIPT_SUMMARY_INPUT_TOKENS,
+): Promise<string | null> {
+  if (msgs.length === 0) return null;
+  let note: string | null = null;
+  for (const chunk of summaryChunks(msgs, budget)) {
+    const input: TranscriptMessage[] = note ? [{ role: 'assistant', content: note } as TranscriptMessage, ...chunk] : chunk;
+    try {
+      const out: string = ((await complete({
+        system: TRANSCRIPT_SUMMARY_PROMPT,
+        user: clip(renderForSummary(input), budget),
+        maxTokens: TRANSCRIPT_SUMMARY_MAX_TOKENS,
+        ...(signal ? { signal } : {}),
+      })) ?? '').trim();
+      if (!out) return null;
+      note = out;
+    } catch {
+      return null;
+    }
+  }
+  return note;
+}

package/src/working/transcript.test.ts

@@ -0,0 +1,125 @@
+/**
+ * src/working/transcript.test.ts
+ * The working-transcript window and fold partitioning (moved unchanged from brain-embedded).
+ */
+import {
+  windowed,
+  compactTailStart,
+  compactTailStartForBudget,
+  verbatimStart,
+  assembleCompacted,
+  pinnedDirectiveIndex,
+  COMPACT_TAIL_TURNS,
+} from './transcript.js';
+import type { TranscriptMessage as ChatCompletionMessage } from './transcript.js';
+
+describe('windowed history (must begin with a user turn)', () => {
+  const msg = (role: ChatCompletionMessage['role'], content = 'x'): ChatCompletionMessage => ({ role, content });
+
+  it('keeps a normal short conversation intact', () => {
+    const convo = [msg('user'), msg('assistant'), msg('user'), msg('assistant')];
+    expect(windowed(convo)).toEqual(convo);
+  });
+
+  it('drops a leading orphaned tool result', () => {
+    const convo = [msg('tool'), msg('user'), msg('assistant')];
+    expect(windowed(convo)[0].role).toBe('user');
+  });
+
+  it('drops a leading assistant turn so the payload starts at a user turn (the googleai 400)', () => {
+    // After a long tool-loop slid the user turn out of the last-N slice, the
+    // window would otherwise start on an assistant tool-call turn — which Gemini
+    // rejects with INVALID_ARGUMENT.
+    const convo = [msg('assistant'), msg('tool'), msg('user'), msg('assistant'), msg('tool')];
+    expect(windowed(convo)[0].role).toBe('user');
+  });
+
+  it('anchors to the last user turn when the window has none (tool loop > window)', () => {
+    // 90 assistant/tool messages after a single user turn: the last-80 slice has
+    // no user turn, so we fall back to the most recent user turn in the full
+    // transcript rather than emit a user-less (invalid) request.
+    const convo: ChatCompletionMessage[] = [msg('user', 'go')];
+    for (let i = 0; i < 90; i++) convo.push(msg(i % 2 === 0 ? 'assistant' : 'tool'));
+    const w = windowed(convo);
+    expect(w[0].role).toBe('user');
+    expect(w[0].content).toBe('go');
+  });
+});
+
+describe('auto-compaction partitioning (summarize the middle, never orphan a tool)', () => {
+  const msg = (role: ChatCompletionMessage['role'], content = 'x'): ChatCompletionMessage => ({ role, content });
+
+  it('walks the tail forward off a leading orphaned tool result', () => {
+    // A tail that would start on a `tool` message (its assistant call is in the
+    // summarized middle) must advance past it so nothing is orphaned.
+    const convo = [msg('user'), msg('assistant'), msg('tool'), msg('assistant'), msg('user')];
+    const start = compactTailStart(convo, 3); // last 3 = [tool, assistant, user]
+    expect(convo[start].role).not.toBe('tool');
+  });
+
+  it('assembled output is [system, memo, active directive, ...tail] and never orphans a tool', () => {
+    const convo: ChatCompletionMessage[] = [msg('user', 'task')];
+    for (let i = 0; i < 30; i++) convo.push(msg(i % 2 === 0 ? 'assistant' : 'tool', `s${i}`));
+    const out = assembleCompacted('SYS', convo, 'MEMO', compactTailStart(convo, COMPACT_TAIL_TURNS));
+    expect(out[0]).toEqual({ role: 'system', content: 'SYS' });
+    // Memo first (the compressed history), THEN the active directive verbatim — not the
+    // other way round, so the model reads the directive as the current instruction.
+    expect(out[1]).toEqual({ role: 'assistant', content: 'MEMO' });
+    expect(out[2].role).toBe('user');
+    expect(out[2].content).toBe('task');
+    // The first tail message after the directive is never an orphaned tool result.
+    expect(out[3].role).not.toBe('tool');
+  });
+
+  it('re-injects the MOST RECENT user directive, not the first, when several fell out of the tail', () => {
+    // The opening request, then a superseding instruction, then a long tool loop that
+    // pushes BOTH out of the verbatim tail. The active directive is the latest one.
+    const convo: ChatCompletionMessage[] = [msg('user', 'run a self-diagnostic'), msg('assistant', 'ok')];
+    convo.push(msg('user', 'now create the gap and fix the code'));
+    for (let i = 0; i < 30; i++) convo.push(msg(i % 2 === 0 ? 'assistant' : 'tool', `s${i}`));
+    const idx = pinnedDirectiveIndex(convo, compactTailStart(convo, COMPACT_TAIL_TURNS));
+    expect(convo[idx].content).toBe('now create the gap and fix the code');
+    const out = assembleCompacted('SYS', convo, 'MEMO', COMPACT_TAIL_TURNS);
+    const directive = out[2];
+    expect(directive.role).toBe('user');
+    expect(directive.content).toBe('now create the gap and fix the code');
+    // The stale opening request is NOT re-injected verbatim (it lives only in the memo).
+    expect(out.filter((m) => m.content === 'run a self-diagnostic')).toHaveLength(0);
+  });
+
+  it('keeps EVERY message from the covered end on — nothing falls between the memo and the tail', () => {
+    // The old fold summarised "all but the last eight" on a turn count, so messages that
+    // slid out of the tail between two folds were in neither the memo nor the tail.
+    const convo: ChatCompletionMessage[] = [msg('user', 'task')];
+    for (let i = 0; i < 30; i++) convo.push(msg('assistant', `a${i}`));
+    const out = assembleCompacted('SYS', convo, 'MEMO', 5);
+    // [system, memo, the covered directive 'task', ...convo[5..]]
+    expect(out[2]).toEqual({ role: 'user', content: 'task' });
+    expect(out.slice(3)).toEqual(convo.slice(5));
+  });
+
+  it('walks the verbatim start off tool results whose call the memo folded', () => {
+    const convo = [msg('user'), msg('assistant'), msg('tool'), msg('tool'), msg('assistant')];
+    expect(verbatimStart(convo, 2)).toBe(4);
+    expect(verbatimStart(convo, 99)).toBe(convo.length);
+  });
+
+  it('sizes the compacted tail by tokens, never below the minimum tail', () => {
+    // Small messages: far more than eight fit, so far more than eight are kept verbatim.
+    const small: ChatCompletionMessage[] = [msg('user', 'task')];
+    for (let i = 0; i < 30; i++) small.push(msg('assistant', 'short'));
+    expect(small.length - compactTailStartForBudget(small, 10_000)).toBeGreaterThan(COMPACT_TAIL_TURNS);
+    // Oversized messages: the minimum tail survives however large it is.
+    const big: ChatCompletionMessage[] = [msg('user', 'task')];
+    for (let i = 0; i < 30; i++) big.push(msg('assistant', 'x'.repeat(40_000)));
+    expect(big.length - compactTailStartForBudget(big, 10_000)).toBe(COMPACT_TAIL_TURNS);
+  });
+
+  it('does not re-inject the directive when the latest user turn already lives in the tail', () => {
+    const convo = [msg('user', 'task'), msg('assistant'), msg('user', 'later')];
+    // Latest user turn ('later') is inside the tail → nothing to re-inject.
+    expect(pinnedDirectiveIndex(convo, compactTailStart(convo, COMPACT_TAIL_TURNS))).toBe(-1);
+    const out = assembleCompacted('SYS', convo, 'MEMO', COMPACT_TAIL_TURNS);
+    expect(out.filter((m) => m.content === 'later')).toHaveLength(1);
+  });
+});

package/src/working/transcript.ts

@@ -0,0 +1,291 @@
+/**
+ * The working transcript — what of a run the model is SHOWN each turn.
+ *
+ * A run's full transcript grows without bound; the request sent to the model must not.
+ * This module owns the two ways it is kept in bounds: the message-count + token WINDOW
+ * (drop-oldest, anchored on a user turn) and AUTO-COMPACTION (fold the older part into a
+ * memory note, keep every later message verbatim). A host supplies only what is
+ * run-specific: the summarizer it calls (see `summary.ts`) and what a fold records.
+ *
+ * Pure except for {@link buildWorkingTranscript}, which awaits the injected summarizer and
+ * updates the caller's `compactMemo`. Generic over the host's message shape: anything with
+ * the OpenAI-style `role` / `content` / `tool_calls` fields (`HandoffMessage`).
+ */
+
+import { defaultEstimateTokens, messageTokens as handoffMessageTokens, tokensOf as handoffTokensOf } from '../handoff/budget.js';
+import type { HandoffMessage } from '../handoff/types.js';
+
+/** A transcript message — the hand-off packer's shape, so both count a message alike. */
+export type TranscriptMessage = HandoffMessage;
+
+/** How much history we send to the model (message-count ceiling). */
+export const HISTORY_WINDOW = 80;
+
+/**
+ * Token budget for the working transcript sent to the model each turn — how much of this
+ * run the model can SEE: the file windows it read, the searches it ran, what it decided.
+ *
+ * It bounds context, which message-count windowing (HISTORY_WINDOW) alone does not: one
+ * `tasks.list` result can be tens of thousands of tokens. It is NOT what keeps a request
+ * inside the serving model's window — the gateway fits every request to a model that can
+ * hold it.
+ *
+ * It was 24k, "sized under the smallest pool model's window". That protected nothing — the
+ * ~16k-token system prompt + tool catalog in front of it already put a full turn at ~40k,
+ * past any 32k window — and it cost every coding run its memory. Six 4k-token file windows
+ * filled it, compaction folded them into a 1.2k-token note, and the model went back for the
+ * files it had just read (chat #105: 55 turns, 63% of calls revisiting, zero edits, prompt
+ * peak 40,351). 64k holds a coding task's working set — a dozen-plus file windows —
+ * verbatim, while a full turn stays well inside the 128k window every coding-capable pool
+ * model has. See {@link windowed} and {@link buildWorkingTranscript}.
+ */
+export const HISTORY_TOKEN_BUDGET = 64_000;
+/**
+ * How much of {@link HISTORY_TOKEN_BUDGET} the verbatim TAIL may keep when the older part
+ * of the transcript is compacted. The rest is headroom new work fills before the next
+ * fold, so the memo is re-folded once per ~20k tokens of progress, not on every turn.
+ */
+export const COMPACT_TAIL_TOKEN_BUDGET = 40_000;
+
+/** Estimated tokens for one message (content + tool-call payload + framing) — THE
+ *  hand-off packer's estimate, so the working transcript and a hand-off to a smaller
+ *  model count a message the same way. */
+function messageTokens(m: TranscriptMessage): number {
+  return handoffMessageTokens(m, defaultEstimateTokens);
+}
+
+/**
+ * The compressed memory of a transcript's older part: `note` summarizes
+ * `transcript[0, coveredEnd)`; every message from `coveredEnd` on is sent verbatim.
+ */
+export interface CompactMemo {
+  note: string;
+  coveredEnd: number;
+}
+
+/**
+ * What the working transcript is built from — the run's full transcript and its cached
+ * compressed memory. {@link buildWorkingTranscript} updates `compactMemo` in place.
+ */
+export interface WorkingTranscriptState<M extends TranscriptMessage = TranscriptMessage> {
+  transcript: M[];
+  compactMemo: CompactMemo | null;
+}
+
+/**
+ * Trim the in-memory transcript to the history window before sending it to the
+ * model. Slicing the last N can leave the window starting on an `assistant`
+ * tool-call turn or an orphaned `tool` result (whose owning call fell off the
+ * front). That payload is invalid for strict vendors: Gemini rejects a request
+ * whose conversation does not begin with a user turn — surfaced as the cascade
+ * `[googleai] 400 INVALID_ARGUMENT` after a long tool-loop crossed the window
+ * boundary. So anchor the window at a user turn.
+ *
+ * If the last-N slice contains no user turn (a tool loop longer than the
+ * window), fall back to the most recent user turn in the FULL transcript and
+ * keep everything after it — correctness over the size cap.
+ */
+export function windowed<M extends TranscriptMessage>(convo: M[]): M[] {
+  let w = convo.slice(-HISTORY_WINDOW);
+  while (w.length > 0 && w[0]!.role !== 'user') w = w.slice(1);
+  if (w.length === 0) {
+    const lastUser = convo.map((m) => m.role).lastIndexOf('user');
+    w = lastUser >= 0 ? convo.slice(lastUser) : convo.slice();
+  }
+  return tokenBounded(w);
+}
+
+/**
+ * Enforce the token budget on an already message-count-windowed slice. Drops the
+ * OLDEST turns first, then re-anchors on a user turn (a strict vendor rejects a window
+ * that doesn't start on `user`, and dropping a turn can orphan a `tool` result whose
+ * `assistant` tool-call fell off the front). The most recent user turn is never
+ * dropped: correctness over the budget when a single turn is itself oversized.
+ */
+function tokenBounded<M extends TranscriptMessage>(w: M[]): M[] {
+  let total = transcriptTokens(w);
+  if (total <= HISTORY_TOKEN_BUDGET) return w;
+  const lastUser = w.map((m) => m.role).lastIndexOf('user');
+  let start = 0;
+  while (total > HISTORY_TOKEN_BUDGET && start < lastUser) {
+    total -= messageTokens(w[start]!);
+    start += 1;
+  }
+  let trimmed = w.slice(start);
+  while (trimmed.length > 1 && trimmed[0]!.role !== 'user') trimmed = trimmed.slice(1);
+  return trimmed;
+}
+
+/**
+ * Is a transcript message still part of what the model sees? False once auto-compaction
+ * has folded it into the memory note, or the drop-oldest window has let it fall off the
+ * front. Deliberately conservative: it judges against the CURRENT transcript (which has
+ * grown since the last working set was built), so it can only ever call a message gone a
+ * turn early — a needless replay costs tokens, a stub for a vanished result costs the run.
+ */
+export function stillInWorkingContext<M extends TranscriptMessage>(state: WorkingTranscriptState<M>, anchor: unknown): boolean {
+  const convo = state.transcript;
+  const idx = convo.indexOf(anchor as M);
+  if (idx < 0) return false;
+  if (state.compactMemo) return idx >= verbatimStart(convo, state.compactMemo.coveredEnd);
+  return windowed(convo).includes(convo[idx]!);
+}
+
+// ---------------------------------------------------------------------------
+// Auto-compaction — summarize the bulky MIDDLE instead of dropping it.
+//
+// `tokenBounded` keeps the request inside the window by DROPPING the oldest turns. That
+// never 413s, but it silently LOSES context — which made a weak model re-read files and
+// thrash ("LOOP EXHAUSTED", chat #50). When a summarizer is available the older turns are
+// compressed into ONE memory note instead, so the model keeps working from a distilled
+// memory. Falls back to `tokenBounded` when no summarizer is reachable.
+//
+// Why this fold is NOT `packHandoff` (`../handoff`): the packer is stateless and gives the
+// verbatim tail priority, handing the note whatever room the tail leaves. The working
+// transcript needs the opposite on both counts — an INCREMENTAL memo reused across turns
+// (one summarizer call per ~20k tokens of progress), a tail capped at
+// COMPACT_TAIL_TOKEN_BUDGET so the note and the next turns have headroom, and a
+// message-count window. What the two share — the token estimate — is the packer's.
+// ---------------------------------------------------------------------------
+
+/** The fewest recent messages the verbatim tail keeps, however large they are. */
+export const COMPACT_TAIL_TURNS = 8;
+
+/** The most recent messages the verbatim tail may hold — half the message window, so a
+ *  compacted transcript stays inside {@link HISTORY_WINDOW} with room to grow. */
+const COMPACT_TAIL_MAX_MESSAGES = HISTORY_WINDOW / 2;
+
+/** The first index at or after `from` that is not a `tool` result: a tool row whose
+ *  assistant call was folded into the memo would be orphaned (strict vendors 400 on it). */
+export function verbatimStart(convo: readonly TranscriptMessage[], from: number): number {
+  let start = Math.max(0, Math.min(from, convo.length));
+  while (start < convo.length && convo[start]!.role === 'tool') start += 1;
+  return start;
+}
+
+/** Start index of the last `tailTurns` messages, walked off a leading `tool` result. */
+export function compactTailStart(convo: readonly TranscriptMessage[], tailTurns: number): number {
+  return verbatimStart(convo, convo.length - tailTurns);
+}
+
+/**
+ * Where the verbatim tail begins when the transcript is compacted: as many of the most
+ * recent messages as fit in `budgetTokens` — never fewer than {@link COMPACT_TAIL_TURNS},
+ * never more than {@link COMPACT_TAIL_MAX_MESSAGES} — walked off a leading tool result.
+ *
+ * Sized by TOKENS, not a message count: a fixed eight messages is four tool results, so
+ * after a fold the fifth file the model needed was always the one it had to read again.
+ */
+export function compactTailStartForBudget(convo: readonly TranscriptMessage[], budgetTokens: number): number {
+  let start = convo.length;
+  let tokens = 0;
+  while (start > 0) {
+    const kept = convo.length - start;
+    if (kept >= COMPACT_TAIL_MAX_MESSAGES) break;
+    const next = messageTokens(convo[start - 1]!);
+    if (kept >= COMPACT_TAIL_TURNS && tokens + next > budgetTokens) break;
+    tokens += next;
+    start -= 1;
+  }
+  return verbatimStart(convo, start);
+}
+
+/**
+ * Index of the MOST RECENT user turn to re-inject verbatim ahead of the tail — the
+ * ACTIVE directive — or -1 when the latest user turn is already inside the tail. Pinning
+ * the FIRST user turn (the old behaviour) made a multi-instruction chat revert to its
+ * opening request (chat #55); the current instruction is always the LATEST user turn.
+ */
+export function pinnedDirectiveIndex(convo: readonly TranscriptMessage[], tailStart: number): number {
+  const lastUser = convo.map((m) => m.role).lastIndexOf('user');
+  return lastUser >= 0 && lastUser < tailStart ? lastUser : -1;
+}
+
+/**
+ * Assemble the working transcript from a compressed-memory `note` that covers
+ * `convo[0, coveredEnd)`: system + the memory note + the ACTIVE user directive re-injected
+ * verbatim (when the note covers it) + EVERY message from `coveredEnd` on (tool-pairing
+ * safe via {@link verbatimStart}). Nothing is in neither the note nor the tail. The
+ * directive sits immediately before the tail so the model reads it as the CURRENT
+ * instruction.
+ */
+export function assembleCompacted<M extends TranscriptMessage>(
+  systemPrompt: string,
+  convo: M[],
+  note: string,
+  coveredEnd: number,
+): M[] {
+  const tailStart = verbatimStart(convo, coveredEnd);
+  const out: M[] = [{ role: 'system', content: systemPrompt } as M];
+  out.push({ role: 'assistant', content: note } as M);
+  const directiveIdx = pinnedDirectiveIndex(convo, tailStart);
+  if (directiveIdx >= 0) out.push(convo[directiveIdx]!);
+  out.push(...convo.slice(tailStart));
+  return out;
+}
+
+/** Estimated tokens of a message list — the ONE count compaction budgets by, exported so
+ *  a run measures what compaction kept out of a call with the same rule. */
+export function transcriptTokens(msgs: readonly TranscriptMessage[]): number {
+  return handoffTokensOf(msgs, defaultEstimateTokens);
+}
+
+/** Can these messages (plus `extraTokens` in front of them) go to the model verbatim —
+ *  inside both the token budget and the message window? */
+function fitsVerbatim(msgs: readonly TranscriptMessage[], extraTokens = 0): boolean {
+  return msgs.length <= HISTORY_WINDOW && extraTokens + transcriptTokens(msgs) <= HISTORY_TOKEN_BUDGET;
+}
+
+/** What a fold reports: how many messages it newly compressed, the note it wrote, and
+ *  the transcript index the note now covers up to (exclusive). */
+export interface TranscriptFold {
+  droppedMessages: number;
+  note: string;
+  coveredEnd: number;
+}
+
+/**
+ * Build the working transcript for a turn. When the whole transcript fits → all of it,
+ * verbatim. Otherwise → a memory note of the older part plus EVERY message after it,
+ * verbatim; `onFolded` is told about each NEW fold, so the caller can record it (a
+ * visible step, a durable consolidation marker).
+ *
+ * The note is folded INCREMENTALLY, and only when it has to be. A note whose verbatim
+ * remainder still fits is reused as-is; once it no longer fits, the previous note plus
+ * exactly the messages since it are folded into a new one, up to a token-sized tail
+ * ({@link compactTailStartForBudget}). Falls back to drop-oldest when the summarizer is
+ * unavailable (`summarize` resolves null). A message-count overflow folds too.
+ */
+export async function buildWorkingTranscript<M extends TranscriptMessage>(
+  state: WorkingTranscriptState<M>,
+  systemPrompt: string,
+  summarize: (msgs: M[]) => Promise<string | null>,
+  onFolded: (fold: TranscriptFold) => void,
+): Promise<M[]> {
+  const convo = state.transcript;
+  if (fitsVerbatim(convo)) {
+    state.compactMemo = null; // back under budget — a later overflow summarizes afresh
+    return [{ role: 'system', content: systemPrompt } as M, ...windowed(convo)];
+  }
+  // A note written against a transcript that has since been replaced covers nothing here.
+  const memo = state.compactMemo && state.compactMemo.coveredEnd <= convo.length ? state.compactMemo : null;
+  if (memo && fitsVerbatim(convo.slice(verbatimStart(convo, memo.coveredEnd)), defaultEstimateTokens(memo.note))) {
+    return assembleCompacted(systemPrompt, convo, memo.note, memo.coveredEnd);
+  }
+  const from = memo?.coveredEnd ?? 0;
+  const to = Math.max(from, compactTailStartForBudget(convo, COMPACT_TAIL_TOKEN_BUDGET));
+  const fold: M[] = memo
+    ? [{ role: 'assistant', content: memo.note } as M, ...convo.slice(from, to)]
+    : convo.slice(from, to);
+  const summary = to > from ? await summarize(fold) : null;
+  if (summary == null) {
+    // Nothing new to fold, or no summarizer: keep the note already held, else drop-oldest.
+    return memo
+      ? assembleCompacted(systemPrompt, convo, memo.note, memo.coveredEnd)
+      : [{ role: 'system', content: systemPrompt } as M, ...windowed(convo)];
+  }
+  const note = `Compressed memory of the earlier part of this conversation:\n${summary}`;
+  state.compactMemo = { note, coveredEnd: to };
+  onFolded({ droppedMessages: to - from, note, coveredEnd: to });
+  return assembleCompacted(systemPrompt, convo, note, to);
+}