@noetic-tools/context 1.1.0 → 1.2.1

package/README.md

@@ -11,9 +11,8 @@ provides:
 - The **lifecycle, budget, and projection machinery** that converges layer
   outputs into the assembled LLM context (`assembleView`, `allocateBudgets`,
   layer state stores, scoping).
-- The **built-in layers**: working memory, history window, observational
-  context, plan, temporal, steering, file reference, static content, durable
-  task state, and the tool context layer.
+- The **built-in layers**: instructions, history, scratchpad, observations,
+  temporal, filesystem, plan, task state, tool calls, and steering.
 
 It depends only on [`@noetic-tools/types`](https://www.npmjs.com/package/@noetic-tools/types).
 [`@noetic-tools/core`](https://www.npmjs.com/package/@noetic-tools/core) builds

package/dist/context/cache-anchoring.d.ts

@@ -0,0 +1,103 @@
+import type { AnchorPin, ContextCacheConfig, ContextCacheStore, ContextEpoch, ContextLayer, ExecutionContext, LayerChurn, LLMResponse, ReanchorReason } from '@noetic-tools/types';
+export type { AnchorPin, ContextCacheConfig, ContextCacheStore, ContextEpoch, LayerChurn, ReanchorReason, } from '@noetic-tools/types';
+/** Defaults for prompt-cache anchoring. See `ContextCacheConfig` for what each one does. */
+export declare const DEFAULT_CONTEXT_CACHE: Required<ContextCacheConfig>;
+/** Fills a partial config with the defaults. */
+export declare function resolveCacheConfig(config?: ContextCacheConfig): Required<ContextCacheConfig>;
+/**
+ * The run of assemblies that share a cacheable prompt prefix.
+ *
+ * A thread at top level, because its turns build one growing conversation. A
+ * child execution keys on itself instead: it inherits its parent's `threadId`
+ * but assembles a different view, so sharing pins would replay a prefix that was
+ * never sent on its behalf.
+ */
+export declare function lineageKey(ctx: ExecutionContext): string;
+/**
+ * Where a layer's pin lives within its epoch.
+ *
+ * The layer id alone, deliberately — the epoch is already scoped to one cache
+ * lineage, and layer ids are unique within a layer set. Folding the layer's
+ * `scope` into the key (as the eventual-recall cache does, where one map spans
+ * every thread) would rotate it every turn for an `'execution'`-scoped layer,
+ * so each turn would retract the "old" pin and add a "new" one for the very
+ * same layer — republishing its content in full, forever.
+ */
+export declare function pinKey(layer: ContextLayer): string;
+export declare function createContextCacheStore(): ContextCacheStore;
+/** Drop a lineage's epoch — used when a child execution ends. */
+export declare function dropLineage(store: ContextCacheStore, key: string): void;
+/** Read a layer's churn record, creating an empty one on first sight. */
+export declare function churnFor(store: ContextCacheStore, key: string): LayerChurn;
+/** Share of watched assemblies in which a layer's output changed, 0–1. */
+export declare function churnRate(churn: LayerChurn): number;
+interface OpenEpochParams {
+    store: ContextCacheStore;
+    key: string;
+    reason: ReanchorReason;
+    instructionsHash: string;
+    layers: ReadonlyArray<ContextLayer>;
+    config: Required<ContextCacheConfig>;
+}
+/**
+ * Start a fresh epoch for a lineage, dropping every pin so the next assembly
+ * re-anchors against current recall output.
+ *
+ * This is the only point at which `'auto'` layers change band: placement is held
+ * still inside an epoch so the prefix cannot shift under the model mid-run.
+ * Churn carries across, decayed, so a layer's band is not relearnt from nothing
+ * each time.
+ */
+export declare function openEpoch({ store, key, reason, instructionsHash, layers, config, }: OpenEpochParams): ContextEpoch;
+/**
+ * Record a lineage as most recently used.
+ *
+ * `Map` keeps first-insertion order, so re-setting an existing key would leave
+ * it where it was and let eviction drop the busiest lineage. Deleting first
+ * moves it to the end, which is what makes eviction least-recently-used.
+ */
+export declare function touchLineage(store: ContextCacheStore, key: string, epoch?: ContextEpoch): void;
+/**
+ * Why the coming assembly must re-anchor, or `undefined` to carry the epoch on.
+ * Ordered cheapest-check first; delta pressure is decided later, once the
+ * supersedes are actually built.
+ */
+export declare function reanchorReason({ epoch, key, instructionsHash, store, config, }: {
+    epoch: ContextEpoch | undefined;
+    key: string;
+    instructionsHash: string;
+    store: ContextCacheStore;
+    config: Required<ContextCacheConfig>;
+}): ReanchorReason | undefined;
+interface NoteCacheOutcomeParams {
+    store: ContextCacheStore;
+    key: string;
+    response: LLMResponse;
+    config: Required<ContextCacheConfig>;
+    /** Tokens the prefix was expected to have cached — system plus anchor band. */
+    expectedTokens: number;
+}
+/**
+ * Judge, from the model's own token report, whether the prompt prefix survived,
+ * and record a re-anchor for the next assembly if it did not.
+ *
+ * Records intent only; pins are never touched here, so a response that steering
+ * later rejects cannot leave the epoch half-rebuilt.
+ *
+ * Three things stop this eating itself:
+ *
+ * - Only the first round counts. Later rounds replay the same view plus tool
+ *   traffic and so hit the cache whatever the first round did — summing them
+ *   hides a total miss behind a busy tool loop.
+ * - Young epochs are spared. The assembly right after a re-anchor writes the
+ *   cache rather than reading it, so its near-zero read is expected, not a miss.
+ * - A provider that reports nothing, or misses persistently, is marked blind and
+ *   stops being consulted. Age and delta pressure still bound the epoch.
+ */
+export declare function noteCacheOutcome({ store, key, response, config, expectedTokens, }: NoteCacheOutcomeParams): void;
+/**
+ * Record a layer's rendered output as the bytes to replay for the rest of the
+ * epoch. The caller sets `epoch.anchorTokens` from the assembled band, which is
+ * measured the same way as the supersedes it gets compared against.
+ */
+export declare function pin(epoch: ContextEpoch, key: string, entry: AnchorPin): void;

package/dist/context/cache-anchoring.js

@@ -0,0 +1,273 @@
+//#region Config
+/** Defaults for prompt-cache anchoring. See `ContextCacheConfig` for what each one does. */
+export const DEFAULT_CONTEXT_CACHE = {
+    enabled: true,
+    minCachedTokens: 100,
+    minEpochAssemblies: 2,
+    maxEpochAssemblies: 50,
+    deltaBudgetFraction: 0.15,
+    autoDemoteChurn: 0.5,
+    autoPromoteChurn: 0.2,
+    minChurnSamples: 3,
+    churnDecay: 0.5,
+};
+/** Fills a partial config with the defaults. */
+export function resolveCacheConfig(config) {
+    return {
+        ...DEFAULT_CONTEXT_CACHE,
+        ...config,
+    };
+}
+/**
+ * Judged assemblies that may come back a miss before the runtime stops steering
+ * on the provider's cache figures. A provider that never caches would otherwise
+ * re-anchor on every turn forever, for no gain.
+ */
+const MAX_CONSECUTIVE_MISSES = 3;
+/** Lineages retained per harness before the least recently used is dropped. */
+const MAX_LINEAGES = 256;
+//#endregion
+//#region Keys
+/**
+ * The run of assemblies that share a cacheable prompt prefix.
+ *
+ * A thread at top level, because its turns build one growing conversation. A
+ * child execution keys on itself instead: it inherits its parent's `threadId`
+ * but assembles a different view, so sharing pins would replay a prefix that was
+ * never sent on its behalf.
+ */
+export function lineageKey(ctx) {
+    return ctx.depth === 0 ? `t:${ctx.threadId}` : `x:${ctx.executionId}`;
+}
+/**
+ * Where a layer's pin lives within its epoch.
+ *
+ * The layer id alone, deliberately — the epoch is already scoped to one cache
+ * lineage, and layer ids are unique within a layer set. Folding the layer's
+ * `scope` into the key (as the eventual-recall cache does, where one map spans
+ * every thread) would rotate it every turn for an `'execution'`-scoped layer,
+ * so each turn would retract the "old" pin and add a "new" one for the very
+ * same layer — republishing its content in full, forever.
+ */
+export function pinKey(layer) {
+    return layer.id;
+}
+//#endregion
+//#region Store
+export function createContextCacheStore() {
+    return {
+        epochs: new Map(),
+        churn: new Map(),
+        pendingReanchor: new Map(),
+    };
+}
+/** Drop a lineage's epoch — used when a child execution ends. */
+export function dropLineage(store, key) {
+    store.epochs.delete(key);
+    store.pendingReanchor.delete(key);
+}
+/** Read a layer's churn record, creating an empty one on first sight. */
+export function churnFor(store, key) {
+    const found = store.churn.get(key);
+    if (found) {
+        return found;
+    }
+    const fresh = {
+        observed: 0,
+        changed: 0,
+        rebillTokens: 0,
+    };
+    store.churn.set(key, fresh);
+    return fresh;
+}
+/** Share of watched assemblies in which a layer's output changed, 0–1. */
+export function churnRate(churn) {
+    return churn.observed === 0 ? 0 : churn.changed / churn.observed;
+}
+/**
+ * Start a fresh epoch for a lineage, dropping every pin so the next assembly
+ * re-anchors against current recall output.
+ *
+ * This is the only point at which `'auto'` layers change band: placement is held
+ * still inside an epoch so the prefix cannot shift under the model mid-run.
+ * Churn carries across, decayed, so a layer's band is not relearnt from nothing
+ * each time.
+ */
+export function openEpoch({ store, key, reason, instructionsHash, layers, config, }) {
+    const previous = store.epochs.get(key);
+    const generation = previous ? Number(previous.id.split('#')[1] ?? 0) + 1 : 0;
+    const autoBand = new Map();
+    for (const layer of layers) {
+        const k = pinKey(layer);
+        autoBand.set(k, chooseBand({
+            store,
+            key: k,
+            current: previous?.autoBand.get(k),
+            config,
+        }));
+    }
+    decayChurn({
+        store,
+        layers,
+        decay: config.churnDecay,
+    });
+    const epoch = {
+        id: `${key}#${generation}`,
+        pins: new Map(),
+        autoBand,
+        instructionsHash,
+        assemblies: 0,
+        anchorTokens: 0,
+        deltaTokens: 0,
+        // A provider that has already shown it reports nothing stays untrusted
+        // across epochs; there is no reason to expect it to start.
+        cacheBlind: previous?.cacheBlind ?? false,
+        // Misses carry across epochs. A miss is what CAUSED this re-anchor, so
+        // resetting here would make the give-up threshold unreachable and leave a
+        // never-caching provider re-anchoring on every turn forever.
+        misses: previous?.misses ?? 0,
+        lastReanchorReason: reason,
+    };
+    store.pendingReanchor.delete(key);
+    touchLineage(store, key, epoch);
+    evictOldestLineages(store);
+    return epoch;
+}
+/**
+ * Record a lineage as most recently used.
+ *
+ * `Map` keeps first-insertion order, so re-setting an existing key would leave
+ * it where it was and let eviction drop the busiest lineage. Deleting first
+ * moves it to the end, which is what makes eviction least-recently-used.
+ */
+export function touchLineage(store, key, epoch) {
+    const current = epoch ?? store.epochs.get(key);
+    if (!current) {
+        return;
+    }
+    store.epochs.delete(key);
+    store.epochs.set(key, current);
+}
+/**
+ * The band an `'auto'` layer takes for the coming epoch.
+ *
+ * The promote and demote thresholds leave a gap on purpose: a layer sitting
+ * between them keeps the band it already had, so one hovering near the boundary
+ * does not flip every epoch and undo the stability the bands exist to provide.
+ */
+function chooseBand({ store, key, current, config, }) {
+    const churn = store.churn.get(key);
+    const band = current ?? 'anchor';
+    if (!churn || churn.observed < config.minChurnSamples) {
+        return band;
+    }
+    const rate = churnRate(churn);
+    if (rate >= config.autoDemoteChurn) {
+        return 'live';
+    }
+    if (rate <= config.autoPromoteChurn) {
+        return 'anchor';
+    }
+    return band;
+}
+function decayChurn({ store, layers, decay, }) {
+    for (const layer of layers) {
+        const churn = store.churn.get(pinKey(layer));
+        if (!churn) {
+            continue;
+        }
+        churn.observed *= decay;
+        churn.changed *= decay;
+        churn.rebillTokens *= decay;
+    }
+}
+/** Keep the lineage map bounded on a long-lived harness that spawns many children. */
+function evictOldestLineages(store) {
+    while (store.epochs.size > MAX_LINEAGES) {
+        const oldest = store.epochs.keys().next();
+        if (oldest.done) {
+            return;
+        }
+        dropLineage(store, oldest.value);
+    }
+}
+/**
+ * Why the coming assembly must re-anchor, or `undefined` to carry the epoch on.
+ * Ordered cheapest-check first; delta pressure is decided later, once the
+ * supersedes are actually built.
+ */
+export function reanchorReason({ epoch, key, instructionsHash, store, config, }) {
+    if (!epoch) {
+        return 'cold-start';
+    }
+    if (epoch.instructionsHash !== instructionsHash) {
+        return 'instructions-changed';
+    }
+    const pending = store.pendingReanchor.get(key);
+    if (pending) {
+        return pending;
+    }
+    if (epoch.assemblies >= config.maxEpochAssemblies) {
+        return 'max-age';
+    }
+    return undefined;
+}
+/**
+ * Judge, from the model's own token report, whether the prompt prefix survived,
+ * and record a re-anchor for the next assembly if it did not.
+ *
+ * Records intent only; pins are never touched here, so a response that steering
+ * later rejects cannot leave the epoch half-rebuilt.
+ *
+ * Three things stop this eating itself:
+ *
+ * - Only the first round counts. Later rounds replay the same view plus tool
+ *   traffic and so hit the cache whatever the first round did — summing them
+ *   hides a total miss behind a busy tool loop.
+ * - Young epochs are spared. The assembly right after a re-anchor writes the
+ *   cache rather than reading it, so its near-zero read is expected, not a miss.
+ * - A provider that reports nothing, or misses persistently, is marked blind and
+ *   stops being consulted. Age and delta pressure still bound the epoch.
+ */
+export function noteCacheOutcome({ store, key, response, config, expectedTokens, }) {
+    const epoch = store.epochs.get(key);
+    if (!epoch || epoch.cacheBlind) {
+        return;
+    }
+    const round = response.rounds?.[0] ?? response.usage;
+    if (!round || round.cachedTokens === undefined) {
+        epoch.cacheBlind = true;
+        return;
+    }
+    // Reads of zero alongside a write mean the prefix was just stored, not missed.
+    if ((round.cacheWriteTokens ?? 0) > 0 && round.cachedTokens === 0) {
+        return;
+    }
+    if (epoch.assemblies < config.minEpochAssemblies) {
+        return;
+    }
+    // Judge against what there actually was to cache: a short prompt can never
+    // reach a fixed floor, and holding it to one would re-anchor forever.
+    const floor = Math.min(config.minCachedTokens, expectedTokens * 0.5);
+    if (round.cachedTokens >= floor) {
+        epoch.misses = 0;
+        return;
+    }
+    epoch.misses += 1;
+    if (epoch.misses >= MAX_CONSECUTIVE_MISSES) {
+        epoch.cacheBlind = true;
+        return;
+    }
+    store.pendingReanchor.set(key, 'cache-miss');
+}
+//#endregion
+//#region Pins
+/**
+ * Record a layer's rendered output as the bytes to replay for the rest of the
+ * epoch. The caller sets `epoch.anchorTokens` from the assembled band, which is
+ * measured the same way as the supersedes it gets compared against.
+ */
+export function pin(epoch, key, entry) {
+    epoch.pins.set(key, entry);
+}
+//#endregion

package/dist/context/layer-lifecycle.d.ts

@@ -172,15 +172,13 @@ export interface RecallCache {
 export declare function createRecallCache(): RecallCache;
 export declare function mostRestrictive(decisions: SteeringDecision[]): SteeringDecision;
 export declare function initLayers({ layers, ctx, storage, store }: InitLayersParams): Promise<void>;
-export declare function recallLayers({ layers, query, ctx, log, budgets, store, itemSchemas, }: RecallLayersParams): Promise<{
-    layerId: string;
-    items: Item[];
-    tokenCount: number;
-}[]>;
+export declare function recallLayers({ layers, query, ctx, log, budgets, store, itemSchemas, }: RecallLayersParams): Promise<RecallEntry[]>;
 type RecallEntry = {
     layerId: string;
     items: Item[];
     tokenCount: number;
+    /** See `RecallLayerOutput.mutatedState` — set when `recall` returned new state. */
+    mutatedState?: boolean;
 };
 interface RecallLayersModeParams extends RecallLayersParams {
     /** When true, treat every layer as atomic regardless of its `recallMode`. */

package/dist/context/layer-lifecycle.js

@@ -278,12 +278,16 @@ export async function recallLayers({ layers, query, ctx, log, budgets, store, it
                 });
                 continue;
             }
+            // Returning state means the render changed something, so it cannot be
+            // replayed from a pin — flag it so view assembly never anchors it.
+            const mutatedState = result.state !== undefined;
             results.push({
                 layerId: layer.id,
                 items: layerSchemas.parseMany(result.items),
                 tokenCount: result.tokenCount,
+                mutatedState,
             });
-            if (result.state !== undefined) {
+            if (mutatedState) {
                 store.set(ctx.executionId, layer.id, result.state);
             }
         }
@@ -340,7 +344,13 @@ export async function recallLayersEventual({ cache, forceAtomic, ...params }) {
             cache.stale.delete(key);
             continue;
         }
-        results.push(cached);
+        // Serving from cache commits nothing, so the flag from the render that
+        // populated it must not ride along — it would force the layer out of the
+        // anchor band for good, on turns where its recall never even ran.
+        results.push({
+            ...cached,
+            mutatedState: false,
+        });
     }
     return results;
 }

package/dist/context/layer-provides.d.ts

@@ -21,7 +21,7 @@ export declare function layerData<T, TState>(opts: {
  * @param opts.execute - Async function receiving args, current state, and execution context.
  * @returns A `LayerFunctionDecl` to include in a layer's `provides`.
  */
-export declare function layerFn<TInput, TOutput, TState>(opts: {
+export declare function layerFunction<TInput, TOutput, TState>(opts: {
     description: string;
     input: ZodType<TInput>;
     output: ZodType<TOutput>;

package/dist/context/layer-provides.js

@@ -22,7 +22,7 @@ export function layerData(opts) {
  * @param opts.execute - Async function receiving args, current state, and execution context.
  * @returns A `LayerFunctionDecl` to include in a layer's `provides`.
  */
-export function layerFn(opts) {
+export function layerFunction(opts) {
     return {
         kind: 'function',
         description: opts.description,

package/dist/context/layer-usage.d.ts

@@ -1,13 +1,28 @@
-import type { Context, LastLayerUsage, RecallLayerOutput, Tool } from '@noetic-tools/types';
+import type { Context, EpochUsage, LastLayerUsage, RecallLayerOutput, Tool } from '@noetic-tools/types';
+/** How a layer's output was banded and pinned for this assembly. */
+export interface LayerServeInfo {
+    placement: 'anchor' | 'live';
+    served: 'fresh' | 'pinned';
+    changed: boolean;
+    churnRate: number;
+    rebillTokens: number;
+}
 interface ComputeLayerUsageParams {
     ctx: Context;
     modelId: string;
     instructions?: string;
     tools?: ReadonlyArray<Tool>;
-    /** Per-layer recall output assembled into the context view for this LLM call. */
+    /**
+     * Per-layer output as it was ACTUALLY served into the view — pinned replays
+     * included. Passing raw recall output here would report content the model
+     * never saw.
+     */
     recallResults: ReadonlyArray<RecallLayerOutput>;
+    /** Banding and pin status per layer id. Absent when context caching is off. */
+    serveInfo?: ReadonlyMap<string, LayerServeInfo>;
+    epoch?: EpochUsage;
 }
-export declare function computeLayerUsage({ ctx, modelId, instructions, tools, recallResults, }: ComputeLayerUsageParams): LastLayerUsage;
+export declare function computeLayerUsage({ ctx, modelId, instructions, tools, recallResults, serveInfo, epoch, }: ComputeLayerUsageParams): LastLayerUsage;
 /** Commit computed usage to the Context, replacing any prior snapshot. */
 export declare function commitLayerUsage(ctx: Context, usage: LastLayerUsage): void;
 export {};

package/dist/context/layer-usage.js

@@ -6,6 +6,13 @@ function canWriteLayerUsage(ctx) {
     }
     return desc.writable !== false;
 }
+const SERVED_FRESH_ANCHOR = {
+    placement: 'anchor',
+    served: 'fresh',
+    changed: false,
+    churnRate: 0,
+    rebillTokens: 0,
+};
 //#endregion
 //#region Helpers
 function estimateJsonTokens(value) {
@@ -18,12 +25,13 @@ function estimateJsonTokens(value) {
 }
 //#endregion
 //#region Public API
-export function computeLayerUsage({ ctx, modelId, instructions, tools, recallResults, }) {
+export function computeLayerUsage({ ctx, modelId, instructions, tools, recallResults, serveInfo, epoch, }) {
     const layers = recallResults
         .map((r) => ({
         layerId: r.layerId,
         tokenCount: r.tokenCount,
         items: r.items,
+        ...(serveInfo?.get(r.layerId) ?? SERVED_FRESH_ANCHOR),
     }))
         .sort((a, b) => a.layerId.localeCompare(b.layerId));
     let historyTokens = 0;
@@ -42,6 +50,7 @@ export function computeLayerUsage({ ctx, modelId, instructions, tools, recallRes
         toolsTokens,
         historyTokens,
         totalUsedTokens,
+        epoch,
     };
 }
 /** Commit computed usage to the Context, replacing any prior snapshot. */

package/dist/context/layers/{file-reference.d.ts → filesystem.d.ts}

@@ -51,5 +51,5 @@ interface FileReferenceOptions {
  *
  * @public
  */
-export declare function fileReference(opts?: FileReferenceOptions): ContextLayer<FileReferenceState>;
+export declare function filesystem(opts?: FileReferenceOptions): ContextLayer<FileReferenceState>;
 export {};

package/dist/context/layers/{file-reference.js → filesystem.js}

@@ -688,6 +688,59 @@ async function recallFileReferences({ state, budget, }) {
         tokenCount: estimateTokens(content),
     };
 }
+/**
+ * Splits a rendered `# Referenced Files` block back into one entry per file,
+ * keyed by the `## <path>` heading.
+ */
+function splitFileBlocks(items) {
+    const blocks = new Map();
+    for (const item of items) {
+        if (item.type !== 'message' || !('content' in item)) {
+            continue;
+        }
+        for (const part of item.content ?? []) {
+            if (!('text' in part) || typeof part.text !== 'string') {
+                continue;
+            }
+            for (const chunk of part.text.split(/\n(?=## )/)) {
+                const heading = chunk.match(/^## (.+)$/m);
+                if (heading?.[1]) {
+                    blocks.set(heading[1].trim(), chunk.trim());
+                }
+            }
+        }
+    }
+    return blocks;
+}
+/**
+ * Describes what changed about the tracked files rather than re-sending all of
+ * them. The whole set is usually large and usually stable, so a change to one
+ * file would otherwise cost a full republish.
+ */
+async function renderFileReferenceDelta({ prev, next, }) {
+    const before = splitFileBlocks(prev);
+    const after = splitFileBlocks(next);
+    const changed = [];
+    for (const [path, block] of after) {
+        if (before.get(path) !== block) {
+            changed.push(block);
+        }
+    }
+    const dropped = [
+        ...before.keys(),
+    ].filter((path) => !after.has(path));
+    if (changed.length === 0 && dropped.length === 0) {
+        return null;
+    }
+    const parts = [];
+    if (changed.length > 0) {
+        parts.push(changed.join('\n\n'));
+    }
+    if (dropped.length > 0) {
+        parts.push(`No longer referenced: ${dropped.join(', ')}`);
+    }
+    return parts.join('\n\n');
+}
 //#endregion
 //#region Layer Factory
 /**
@@ -704,15 +757,18 @@ async function recallFileReferences({ state, budget, }) {
  *
  * @public
  */
-export function fileReference(opts) {
+export function filesystem(opts) {
     const runtime = createFileReferenceRuntime(opts);
     return {
-        id: 'file-reference',
-        name: 'File Reference',
+        id: 'filesystem',
+        name: 'Filesystem',
         slot: runtime.slot,
         scope: 'thread',
         budget: 'auto',
         rerenderTiming: 'immediate',
+        // A large payload that changes rarely, and only a file at a time — the case
+        // anchoring plus a compact supersede is worth the most on.
+        placement: 'anchor',
         timeouts: {
             // onItemAppend reads files AND runs an LLM scoring call per new
             // reference (parallelized) — the 5s pipeline default silently drops the
@@ -723,6 +779,7 @@ export function fileReference(opts) {
             init: () => initFileReferenceState(runtime.baseDir),
             onItemAppend: (args) => onFileReferenceItemAppend(args, runtime),
             recall: recallFileReferences,
+            renderDelta: renderFileReferenceDelta,
         },
     };
 }

package/dist/context/layers/{history-window.d.ts → history.d.ts}

@@ -15,17 +15,17 @@
  *      slice boundary via `stripUnresolvedToolCalls`.
  */
 import type { ContextLayer } from '@noetic-tools/types';
-/** @public Configuration for the {@link historyWindow} layer. */
-export interface HistoryWindowConfig {
+/** @public Configuration for the {@link history} layer. */
+export interface HistoryConfig {
     /** Cap on the number of trailing items projected to the LLM. Defaults to 40. */
     maxItems?: number;
 }
 /**
- * Creates a history-window context layer that caps the trailing items projected
+ * Creates a history context layer that caps the trailing items projected
  * to the LLM. Storage stays unbounded; only the wire payload is narrowed.
  *
  * @public
  * @param config - Optional `{ maxItems }`. Defaults to 40.
  * @returns A `ContextLayer` that contributes only a `projectHistory` hook.
  */
-export declare function historyWindow(config?: HistoryWindowConfig): ContextLayer<null>;
+export declare function history(config?: HistoryConfig): ContextLayer<null>;