@seanhogg/builderforce-memory 2026.10.24 → 2026.10.25

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 first ${to} message(s) of this conversation:\n${summary}`;
+  state.compactMemo = { note, coveredEnd: to };
+  onFolded({ droppedMessages: to - from, note, coveredEnd: to });
+  return assembleCompacted(systemPrompt, convo, note, to);
+}