@seanhogg/builderforce-memory 2026.10.25 → 2026.10.27

package/dist/working/summary.js

@@ -5,6 +5,7 @@
  * rendered for it, so a compaction note, a hand-off note and a "Consolidate" summary read
  * the same everywhere.
  */
+import { transcriptTokens } 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.';
 /**
@@ -13,6 +14,13 @@ export const TRANSCRIPT_SUMMARY_PROMPT = 'You compress an in-progress AI agent t
  * 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;
 /** Render a slice of the transcript to the compact text the summarizer compresses. */
 export function renderForSummary(msgs) {
     return msgs
@@ -26,23 +34,59 @@ export function renderForSummary(msgs) {
         .join('\n\n');
 }
 /**
- * Compress `msgs` into a memory note. Null on any failure or an empty answer, so the
- * caller falls back (drop-oldest, elision, "nothing to consolidate").
+ * 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 async function summarizeTranscript(complete, msgs, signal) {
-    if (msgs.length === 0)
-        return null;
-    try {
-        const out = ((await complete({
-            system: TRANSCRIPT_SUMMARY_PROMPT,
-            user: renderForSummary(msgs),
-            maxTokens: TRANSCRIPT_SUMMARY_MAX_TOKENS,
-            ...(signal ? { signal } : {}),
-        })) ?? '').trim();
-        return out.length > 0 ? out : null;
+export function summaryChunks(msgs, budget = TRANSCRIPT_SUMMARY_INPUT_TOKENS) {
+    const chunks = [];
+    let chunk = [];
+    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;
     }
-    catch {
+    if (chunk.length > 0)
+        chunks.push(chunk);
+    return chunks;
+}
+/** ~4 characters a token: the rendered text one call may carry. */
+const clip = (text, budget) => {
+    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, msgs, signal, budget = TRANSCRIPT_SUMMARY_INPUT_TOKENS) {
+    if (msgs.length === 0)
         return null;
+    let note = null;
+    for (const chunk of summaryChunks(msgs, budget)) {
+        const input = note ? [{ role: 'assistant', content: note }, ...chunk] : chunk;
+        try {
+            const out = ((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;
 }
 //# sourceMappingURL=summary.js.map

package/dist/working/summary.js.map

@@ -1 +1 @@
-{"version":3,"file":"summary.js","sourceRoot":"","sources":["../../src/working/summary.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,qCAAqC;AACrC,MAAM,CAAC,MAAM,yBAAyB,GACpC,6pBAA6pB,CAAC;AAEhqB;;;;GAIG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,KAAK,CAAC;AAcnD,sFAAsF;AACtF,MAAM,UAAU,gBAAgB,CAAC,IAAkC;IACjE,OAAO,IAAI;SACR,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACT,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;QAC5F,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC;YAClE,CAAC,CAAC,aAAc,CAAC,CAAC,UAA8B,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YAC7J,CAAC,CAAC,EAAE,CAAC;QACP,OAAO,GAAG,CAAC,CAAC,IAAI,GAAG,KAAK,KAAK,OAAO,EAAE,CAAC;IACzC,CAAC,CAAC;SACD,IAAI,CAAC,MAAM,CAAC,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,QAA2B,EAC3B,IAAkC,EAClC,MAAoB;IAEpB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,CAAC,CAAC,MAAM,QAAQ,CAAC;YAC3B,MAAM,EAAE,yBAAyB;YACjC,IAAI,EAAE,gBAAgB,CAAC,IAAI,CAAC;YAC5B,SAAS,EAAE,6BAA6B;YACxC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9B,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAClB,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"summary.js","sourceRoot":"","sources":["../../src/working/summary.ts"],"names":[],"mappings":"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"}

package/dist/working/transcript.d.ts

@@ -58,17 +58,35 @@ export interface WorkingTranscriptState<M extends TranscriptMessage = Transcript
     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.
+ * How far the message window's front moves at a time — a quarter of
+ * {@link HISTORY_WINDOW}. See {@link windowed}.
+ */
+export declare const HISTORY_WINDOW_DROP_CHUNK: number;
+/**
+ * How far (in tokens) the token window's front moves at a time — a quarter of
+ * {@link HISTORY_TOKEN_BUDGET}, so a drop leaves the window at ~75% of the budget and
+ * the next one waits for ~16k tokens of new work. See {@link windowed}.
+ */
+export declare const HISTORY_TOKEN_DROP_CHUNK: number;
+/**
+ * Trim the in-memory transcript to the history window — the message-count window
+ * ({@link HISTORY_WINDOW}) and the token budget ({@link HISTORY_TOKEN_BUDGET}) — before
+ * sending it to the model.
+ *
+ * The OLDEST turns go first, in CHUNKS with hysteresis: once over, the front jumps to
+ * the next fixed cut point ({@link HISTORY_WINDOW_DROP_CHUNK} messages /
+ * {@link HISTORY_TOKEN_DROP_CHUNK} tokens), leaving room the following turns fill before
+ * it moves again. Dropping exactly to the limit slid the front by a message or two on
+ * every turn, so the request's prefix changed every turn and no provider prefix cache
+ * could hit past the system prompt.
  *
- * 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.
+ * The window is then anchored at a user turn: a window starting on an `assistant`
+ * tool-call turn or an orphaned `tool` result (whose owning call fell off the front) is
+ * invalid for strict vendors — Gemini rejects a request whose conversation does not
+ * begin with a user turn (the cascade `[googleai] 400 INVALID_ARGUMENT` after a long
+ * tool loop crossed the window boundary). The most recent user turn is never dropped:
+ * correctness over the size cap, when a tool loop outgrows the window or a single turn
+ * is itself oversized.
  */
 export declare function windowed<M extends TranscriptMessage>(convo: M[]): M[];
 /**

package/dist/working/transcript.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../../src/working/transcript.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,yFAAyF;AACzF,MAAM,MAAM,iBAAiB,GAAG,cAAc,CAAC;AAE/C,qEAAqE;AACrE,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAC3C;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAShD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB,CAAC,CAAC,SAAS,iBAAiB,GAAG,iBAAiB;IACrF,UAAU,EAAE,CAAC,EAAE,CAAC;IAChB,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;CACjC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,iBAAiB,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAQrE;AAuBD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,iBAAiB,EAAE,KAAK,EAAE,sBAAsB,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAM7H;AAmBD,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAMpC;4FAC4F;AAC5F,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIvF;AAED,wFAAwF;AACxF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE/F;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAY3G;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAGnG;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,iBAAiB,EAC3D,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,CAAC,EAAE,EACV,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,GACjB,CAAC,EAAE,CAQL;AAED;4EAC4E;AAC5E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,iBAAiB,EAAE,GAAG,MAAM,CAE3E;AAQD;kEACkE;AAClE,MAAM,WAAW,cAAc;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,SAAS,iBAAiB,EACtE,KAAK,EAAE,sBAAsB,CAAC,CAAC,CAAC,EAChC,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,EAChD,QAAQ,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,GACvC,OAAO,CAAC,CAAC,EAAE,CAAC,CA2Bd"}
+{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../../src/working/transcript.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,yFAAyF;AACzF,MAAM,MAAM,iBAAiB,GAAG,cAAc,CAAC;AAE/C,qEAAqE;AACrE,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAC3C;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAShD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB,CAAC,CAAC,SAAS,iBAAiB,GAAG,iBAAiB;IACrF,UAAU,EAAE,CAAC,EAAE,CAAC;IAChB,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;CACjC;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB,QAAqB,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,QAA2B,CAAC;AAoCjE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,iBAAiB,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAMrE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,iBAAiB,EAAE,KAAK,EAAE,sBAAsB,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAM7H;AAmBD,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAMpC;4FAC4F;AAC5F,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIvF;AAED,wFAAwF;AACxF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE/F;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAY3G;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAGnG;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,iBAAiB,EAC3D,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,CAAC,EAAE,EACV,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,GACjB,CAAC,EAAE,CAQL;AAED;4EAC4E;AAC5E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,iBAAiB,EAAE,GAAG,MAAM,CAE3E;AAQD;kEACkE;AAClE,MAAM,WAAW,cAAc;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,SAAS,iBAAiB,EACtE,KAAK,EAAE,sBAAsB,CAAC,CAAC,CAAC,EAChC,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,EAChD,QAAQ,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,GACvC,OAAO,CAAC,CAAC,EAAE,CAAC,CA2Bd"}

package/dist/working/transcript.js

@@ -46,49 +46,81 @@ function messageTokens(m) {
     return handoffMessageTokens(m, defaultEstimateTokens);
 }
 /**
- * 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.
+ * How far the message window's front moves at a time — a quarter of
+ * {@link HISTORY_WINDOW}. See {@link windowed}.
  */
-export function windowed(convo) {
-    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();
+export const HISTORY_WINDOW_DROP_CHUNK = HISTORY_WINDOW / 4;
+/**
+ * How far (in tokens) the token window's front moves at a time — a quarter of
+ * {@link HISTORY_TOKEN_BUDGET}, so a drop leaves the window at ~75% of the budget and
+ * the next one waits for ~16k tokens of new work. See {@link windowed}.
+ */
+export const HISTORY_TOKEN_DROP_CHUNK = HISTORY_TOKEN_BUDGET / 4;
+/**
+ * Where the message-count window begins: 0 while the transcript fits
+ * {@link HISTORY_WINDOW}, else the first multiple of {@link HISTORY_WINDOW_DROP_CHUNK}
+ * that brings it back under. The cut points are fixed positions in the transcript, so
+ * the front stays put while new messages arrive and jumps a whole chunk when it moves.
+ */
+function messageWindowStart(length) {
+    if (length <= HISTORY_WINDOW)
+        return 0;
+    return Math.ceil((length - HISTORY_WINDOW) / HISTORY_WINDOW_DROP_CHUNK) * HISTORY_WINDOW_DROP_CHUNK;
+}
+/**
+ * Where the token window begins: 0 while the transcript fits
+ * {@link HISTORY_TOKEN_BUDGET}, else the first cut point that brings it back under. A
+ * cut point is the message after which the transcript's running total crosses a multiple
+ * of {@link HISTORY_TOKEN_DROP_CHUNK} — counted from the transcript's own start, so a
+ * cut point never moves as the transcript grows at the end.
+ */
+function tokenWindowStart(convo) {
+    const sizes = convo.map(messageTokens);
+    let remaining = sizes.reduce((sum, n) => sum + n, 0);
+    if (remaining <= HISTORY_TOKEN_BUDGET)
+        return 0;
+    let dropped = 0;
+    let nextCut = HISTORY_TOKEN_DROP_CHUNK;
+    for (let i = 0; i < convo.length; i++) {
+        dropped += sizes[i];
+        remaining -= sizes[i];
+        if (dropped < nextCut)
+            continue;
+        while (dropped >= nextCut)
+            nextCut += HISTORY_TOKEN_DROP_CHUNK;
+        if (remaining <= HISTORY_TOKEN_BUDGET)
+            return i + 1;
     }
-    return tokenBounded(w);
+    return convo.length;
 }
 /**
- * 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.
+ * Trim the in-memory transcript to the history window — the message-count window
+ * ({@link HISTORY_WINDOW}) and the token budget ({@link HISTORY_TOKEN_BUDGET}) — before
+ * sending it to the model.
+ *
+ * The OLDEST turns go first, in CHUNKS with hysteresis: once over, the front jumps to
+ * the next fixed cut point ({@link HISTORY_WINDOW_DROP_CHUNK} messages /
+ * {@link HISTORY_TOKEN_DROP_CHUNK} tokens), leaving room the following turns fill before
+ * it moves again. Dropping exactly to the limit slid the front by a message or two on
+ * every turn, so the request's prefix changed every turn and no provider prefix cache
+ * could hit past the system prompt.
+ *
+ * The window is then anchored at a user turn: a window starting on an `assistant`
+ * tool-call turn or an orphaned `tool` result (whose owning call fell off the front) is
+ * invalid for strict vendors — Gemini rejects a request whose conversation does not
+ * begin with a user turn (the cascade `[googleai] 400 INVALID_ARGUMENT` after a long
+ * tool loop crossed the window boundary). The most recent user turn is never dropped:
+ * correctness over the size cap, when a tool loop outgrows the window or a single turn
+ * is itself oversized.
  */
-function tokenBounded(w) {
-    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]);
+export function windowed(convo) {
+    const lastUser = convo.map((m) => m.role).lastIndexOf('user');
+    if (lastUser < 0)
+        return transcriptTokens(convo) <= HISTORY_TOKEN_BUDGET ? convo.slice() : convo.slice(-1);
+    let start = Math.min(Math.max(messageWindowStart(convo.length), tokenWindowStart(convo)), lastUser);
+    while (convo[start].role !== 'user')
         start += 1;
-    }
-    let trimmed = w.slice(start);
-    while (trimmed.length > 1 && trimmed[0].role !== 'user')
-        trimmed = trimmed.slice(1);
-    return trimmed;
+    return convo.slice(start);
 }
 /**
  * Is a transcript message still part of what the model sees? False once auto-compaction
@@ -109,11 +141,11 @@ export function stillInWorkingContext(state, anchor) {
 // ---------------------------------------------------------------------------
 // Auto-compaction — summarize the bulky MIDDLE instead of dropping it.
 //
-// `tokenBounded` keeps the request inside the window by DROPPING the oldest turns. That
+// `windowed` 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.
+// memory. Falls back to `windowed` 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
@@ -235,7 +267,7 @@ export async function buildWorkingTranscript(state, systemPrompt, summarize, onF
             ? assembleCompacted(systemPrompt, convo, memo.note, memo.coveredEnd)
             : [{ role: 'system', content: systemPrompt }, ...windowed(convo)];
     }
-    const note = `Compressed memory of the first ${to} message(s) of this conversation:\n${summary}`;
+    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);

package/dist/working/transcript.js.map

@@ -1 +1 @@
-{"version":3,"file":"transcript.js","sourceRoot":"","sources":["../../src/working/transcript.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"transcript.js","sourceRoot":"","sources":["../../src/working/transcript.ts"],"names":[],"mappings":"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"}

package/dist/working/types.d.ts

@@ -29,5 +29,11 @@ export interface ConsolidateOptions {
     at?: Date;
     /** The workspace root — absolute paths under it are kept, made relative. */
     root?: string;
+    /**
+     * Distinct files (changed, deleted and read together) a run must touch for its map to
+     * be kept. Defaults to `MIN_CONSOLIDATED_FILES`; the same floor applies to a run that
+     * changed files as to one that only read.
+     */
+    minFiles?: number;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/working/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/working/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,gFAAgF;AAChF,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC,wFAAwF;AACxF,MAAM,WAAW,qBAAqB;IACpC,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,wFAAwF;AACxF,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,EAAE,CAAC,EAAE,IAAI,CAAC;IACV,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/working/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,gFAAgF;AAChF,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC,wFAAwF;AACxF,MAAM,WAAW,qBAAqB;IACpC,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,wFAAwF;AACxF,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,EAAE,CAAC,EAAE,IAAI,CAAC;IACV,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanhogg/builderforce-memory",
-  "version": "2026.10.25",
+  "version": "2026.10.27",
   "description": "BuilderForce Agent Memory — runtime layer. SSM execution, Transformer orchestration, online distillation, enterprise RAG (ingestion pipelines, vector-store adapters, tenant/ACL-scoped hybrid retrieval), multi-agent graph orchestration, LLM telemetry and cost accounting, and persistent agent memory for BuilderForce.ai agents.",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -103,7 +103,7 @@
   },
   "homepage": "https://github.com/SeanHogg/builderforce-memory/tree/main/packages/memory#readme",
   "peerDependencies": {
-    "@seanhogg/builderforce-memory-engine": "^2026.10.25"
+    "@seanhogg/builderforce-memory-engine": "^2026.10.27"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
@@ -117,7 +117,7 @@
     "ts-jest": "^29.2.0",
     "typescript": "^6.0.3",
     "@typescript/native-preview": "7.0.0-dev.20260627.2",
-    "@seanhogg/builderforce-memory-engine": "2026.10.25"
+    "@seanhogg/builderforce-memory-engine": "2026.10.27"
   },
   "jest": {
     "preset": "ts-jest/presets/default-esm",

package/src/working/codemap.test.ts

@@ -0,0 +1,144 @@
+/**
+ * src/working/codemap.test.ts
+ * Code maps (2026.10.27): the 3-file floor for every run, the root area, reading a
+ * stored map back, and which maps a run is handed.
+ */
+
+import {
+  CONSOLIDATED_ROOT_AREA,
+  areaOfPath,
+  areasNamedIn,
+  areasOfPathsIn,
+  consolidate,
+  consolidatedArea,
+  consolidatedFactsFor,
+  consolidatedFiles,
+  mergeConsolidated,
+  withoutConsolidatedFiles,
+  type WorkingMemorySnapshot,
+} from './index.js';
+
+const AT = new Date('2026-10-26T12:00:00Z');
+
+function snap(partial: Partial<WorkingMemorySnapshot>): WorkingMemorySnapshot {
+  return { created: [], edited: [], deleted: [], read: [], searched: [], ...partial };
+}
+
+describe('consolidate — the minimum holds for every run', () => {
+  it('skips a one- or two-file run that changed files', () => {
+    expect(consolidate(snap({ edited: ['api/src/r/x.ts'] }))).toBeNull();
+    expect(consolidate(snap({ edited: ['api/src/r/x.ts'], read: ['api/src/r/y.ts'] }))).toBeNull();
+    expect(consolidate(snap({ created: ['api/src/r/x.ts'], deleted: ['api/src/r/old.ts'] }))).toBeNull();
+  });
+
+  it('counts changed and read files together', () => {
+    const c = consolidate(snap({ edited: ['api/src/r/x.ts'], read: ['api/src/r/y.ts', 'api/src/r/z.ts'] }), { at: AT });
+    expect(c?.key).toBe('codemap:api/src/r');
+  });
+
+  it('counts a file once however it was touched', () => {
+    expect(consolidate(snap({ edited: ['a/b/x.ts'], read: ['a/b/x.ts', 'a/b/x.ts', 'a/b/y.ts'] }))).toBeNull();
+  });
+
+  it('does not count noise it drops', () => {
+    expect(consolidate(snap({ edited: ['a/b/x.ts'], read: ['pnpm-lock.yaml', 'node_modules/p/i.js', 'a/b/y.ts'] }))).toBeNull();
+  });
+});
+
+describe('consolidate — root files', () => {
+  it('files a root-only run under the root area', () => {
+    const c = consolidate(snap({ edited: ['DONE.md', 'ROADMAP.md'], read: ['package.json'] }), { at: AT })!;
+    expect(c.key).toBe(`codemap:${CONSOLIDATED_ROOT_AREA}`);
+  });
+
+  it('maps a root file to the same area a reader resolves it to', () => {
+    const c = consolidate(snap({ read: ['README.md', 'package.json', 'tsconfig.json'] }), { at: AT })!;
+    expect(consolidatedArea(c.key)).toBe(areaOfPath('README.md'));
+    expect(consolidatedFactsFor([c], [areaOfPath('package.json')])).toEqual([c]);
+  });
+});
+
+describe('areaOfPath', () => {
+  it('is a file\'s directory, a directory itself, or the root area', () => {
+    expect(areaOfPath('web/src/a.ts')).toBe('web/src');
+    expect(areaOfPath('.\\web\\src\\a.ts')).toBe('web/src');
+    expect(areaOfPath('clients/vscode/src')).toBe('clients/vscode/src');
+    expect(areaOfPath('DONE.md')).toBe(CONSOLIDATED_ROOT_AREA);
+    expect(areaOfPath('  ')).toBe('');
+  });
+});
+
+describe('areasOfPathsIn', () => {
+  it('takes the areas of the repo-relative paths a text names', () => {
+    expect(areasOfPathsIn('Touches `brain-embedded/src/runStore/dispatchTool.ts` and C:/abs/x.ts, see (docs/specs/35.md).')).toEqual([
+      'brain-embedded/src/runStore',
+      'docs/specs',
+    ]);
+  });
+
+  it('maps a root file to the root area and skips what is not a repo path', () => {
+    expect(areasOfPathsIn('bump package.json, e.g. now')).toEqual([CONSOLIDATED_ROOT_AREA]);
+    expect(areasOfPathsIn('see https://x.dev/a/b.ts and /etc/hosts and ../up/x.ts')).toEqual([]);
+  });
+});
+
+describe('reading a stored map back', () => {
+  const map = consolidate(snap({ read: ['w/s/a.ts', 'w/s/b.ts'], edited: ['w/s/c.ts'] }), { at: AT })!;
+
+  it('lists the files a map names, never a deletion', () => {
+    expect(consolidatedFiles(map.content)).toEqual(['w/s/c.ts', 'w/s/a.ts', 'w/s/b.ts']);
+    expect(consolidatedFiles('Code map\n- x/y.ts (deleted)\n- x/z.ts')).toEqual(['x/z.ts']);
+  });
+
+  it('drops a changed file from the map and keeps the rest', () => {
+    const out = withoutConsolidatedFiles(map.content, ['W\\S\\A.ts'])!;
+    expect(out).not.toContain('w/s/a.ts');
+    expect(out).toContain('- w/s/c.ts (changed)');
+    expect(out).toContain('- w/s/b.ts');
+    expect(out.split('\n')[0]).toBe(map.content.split('\n')[0]);
+  });
+
+  it('returns null once no file is left', () => {
+    expect(withoutConsolidatedFiles(map.content, ['w/s/a.ts', 'w/s/b.ts', 'w/s/c.ts'])).toBeNull();
+  });
+
+  it('leaves the map as it was when nothing named is in it', () => {
+    expect(withoutConsolidatedFiles(map.content, ['other.ts'])).toBe(map.content);
+  });
+
+  it('reads a merged map the same way', () => {
+    const next = consolidate(snap({ edited: ['w/s/d.ts', 'w/s/e.ts', 'w/s/f.ts'] }), { at: AT })!;
+    expect(consolidatedFiles(mergeConsolidated(next.key, map.content, next.content))).toEqual([
+      'w/s/d.ts', 'w/s/e.ts', 'w/s/f.ts', 'w/s/c.ts', 'w/s/a.ts', 'w/s/b.ts',
+    ]);
+  });
+});
+
+describe('which maps a run is handed', () => {
+  const facts = [
+    { key: 'codemap:brain-embedded/src', content: 'wide' },
+    { key: 'learned:x', content: 'not a map' },
+    { key: 'codemap:brain-embedded/src/runStore', content: 'narrow' },
+    { key: 'codemap:api/src', content: 'elsewhere' },
+    { key: 'codemap:(root)', content: 'root' },
+  ];
+
+  it('keeps overlapping maps only, most specific first, capped', () => {
+    expect(consolidatedFactsFor(facts, ['brain-embedded/src/runStore']).map((f) => f.content)).toEqual(['narrow', 'wide']);
+    expect(consolidatedFactsFor(facts, ['brain-embedded/src/runStore'], 1).map((f) => f.content)).toEqual(['narrow']);
+    expect(consolidatedFactsFor(facts, ['(root)']).map((f) => f.content)).toEqual(['root']);
+    expect(consolidatedFactsFor(facts, [])).toEqual([]);
+  });
+
+  it('finds the areas a request names by word', () => {
+    const areas = facts.map((f) => consolidatedArea(f.key)).filter((a): a is string => !!a);
+    expect(areasNamedIn('the run store drops a steer', areas)).toEqual(['brain-embedded/src/runStore']);
+    expect(areasNamedIn('Why does runStore retry?', areas)).toEqual(['brain-embedded/src/runStore']);
+    expect(areasNamedIn('brain-embedded build is slow', areas)).toEqual(['brain-embedded/src/runStore', 'brain-embedded/src']);
+  });
+
+  it('never matches on a generic or short directory name', () => {
+    expect(areasNamedIn('fix the src api', ['api/src', 'web/src'])).toEqual([]);
+    expect(areasNamedIn('', ['api/src'])).toEqual([]);
+  });
+});