@noetic-tools/core 5.2.0 → 5.3.0

package/dist/adapters/openrouter.d.ts

@@ -23,7 +23,14 @@ export declare function itemsToInput(items: ReadonlyArray<Item>): OpenRouterInpu
  * when the output array contains no message items.
  */
 export declare function extractOutputItems(response: OpenRouterAgent.OpenResponsesResult): Item[];
-/** @internal */
+/**
+ * @internal
+ *
+ * A missing `cachedTokens` stays `undefined` rather than collapsing to `0`:
+ * context anchoring reads it to decide whether the prompt prefix survived, and
+ * "this provider reports no cache figures" must not look like "nothing was
+ * cached".
+ */
 export declare function extractUsage(usage: OpenRouterAgent.Usage | null | undefined): LLMResponse['usage'];
 /**
  * Provider APIs (Anthropic via OpenRouter) enforce tool names match

package/dist/adapters/openrouter.js

@@ -153,7 +153,14 @@ export function extractOutputItems(response) {
         ...items,
     ];
 }
-/** @internal */
+/**
+ * @internal
+ *
+ * A missing `cachedTokens` stays `undefined` rather than collapsing to `0`:
+ * context anchoring reads it to decide whether the prompt prefix survived, and
+ * "this provider reports no cache figures" must not look like "nothing was
+ * cached".
+ */
 export function extractUsage(usage) {
     if (!usage) {
         return {
@@ -165,8 +172,23 @@ export function extractUsage(usage) {
         inputTokens: usage.inputTokens,
         outputTokens: usage.outputTokens,
         cachedTokens: usage.inputTokensDetails?.cachedTokens,
+        cacheWriteTokens: cacheWriteTokensOf(usage.inputTokensDetails),
     };
 }
+/**
+ * OpenRouter reports `cache_write_tokens` alongside `cached_tokens`, but the
+ * SDK's `InputTokensDetails` type declares only the latter. Read it off the
+ * value rather than the type, and stay `undefined` when it is genuinely absent
+ * — a write of zero and no report at all mean different things to the epoch
+ * logic (see `noteCacheOutcome`).
+ */
+function cacheWriteTokensOf(details) {
+    if (typeof details !== 'object' || details === null || !('cacheWriteTokens' in details)) {
+        return undefined;
+    }
+    const value = details.cacheWriteTokens;
+    return typeof value === 'number' ? value : undefined;
+}
 //#endregion
 //#region Tool Conversion
 // We construct the SDK tool shape manually and use frameworkCast to bridge

package/dist/harness/agent-harness.d.ts

@@ -2,7 +2,7 @@ import { ItemSchemaRegistry } from '@noetic-tools/types';
 import type { LayerStateStore, RecallCache } from './deps/context.js';
 import type { DetachedSpawnOverrides } from './deps/interpreter.js';
 import type { CheckpointStore, EventBroadcaster, RestoreCheckpointOptions, StepLedgerRetention, StepLedgerStore } from './deps/runtime.js';
-import type { AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, Channel, ChannelHandle, Context, ContextData, ContextLayer, CwdState, DeliveryMode, DetachedHandle, ExecuteInput, ExecuteOptions, ExternalChannel, FsAdapter, HarnessResponse, HarnessStatus, Item, ItemSchemaExtensions, LLMResponse, LlmProviderConfig, ProjectionPolicy, RecallLayerOutput, SessionScope, ShellAdapter, Span, SteeringDecision, Step, StorageAdapter, StreamEvent, StreamingItem, SubHarnessSession, SubprocessAdapter, Tool, TraceExporter, ZodType } from './deps/types.js';
+import type { AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, Channel, ChannelHandle, Context, ContextCacheConfig, ContextCacheStore, ContextData, ContextLayer, CwdState, DeliveryMode, DetachedHandle, ExecuteInput, ExecuteOptions, ExternalChannel, FsAdapter, HarnessResponse, HarnessStatus, Item, ItemSchemaExtensions, LLMResponse, LlmProviderConfig, ProjectionPolicy, RecallLayerOutput, SessionScope, ShellAdapter, Span, SteeringDecision, Step, StorageAdapter, StreamEvent, StreamingItem, SubHarnessSession, SubprocessAdapter, Tool, TraceExporter, ZodType } from './deps/types.js';
 export { createStreamIdleWatchdog } from './model-call.js';
 interface AgentHarnessOpts<TParams extends Record<string, unknown> = Record<string, unknown>> {
     name: string;
@@ -52,6 +52,8 @@ interface AgentHarnessOpts<TParams extends Record<string, unknown> = Record<stri
     projection?: ProjectionPolicy;
     /** When true, every layer is recalled atomically regardless of its `recallMode`. */
     forceAtomicRecall?: boolean;
+    /** Tuning for prompt-cache anchoring. See `ContextCacheConfig` for the defaults. */
+    contextCache?: ContextCacheConfig;
     traceExporter?: TraceExporter;
     layerStateStore?: LayerStateStore;
     /** Default delivery mode for messages that don't specify one. Defaults to `next-turn`. */
@@ -152,6 +154,8 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
     readonly layerStateStore: LayerStateStore;
     /** Per-harness memoization cache for `recallMode: 'eventual'` layers. */
     readonly recallCache: RecallCache;
+    /** Per-harness pinned anchor output and epoch bookkeeping, keyed by cache lineage. */
+    readonly contextCache: ContextCacheStore;
     /**
      * Execution ids whose layer `init` hooks have already run, so repeated/nested
      * `run()` calls and the session turn path never re-init (which would clobber

package/dist/harness/agent-harness.js

@@ -2,8 +2,8 @@ import { frameworkCast, ItemSchemaRegistry, NoeticConfigError } from '@noetic-to
 import { SpanImpl } from '../observability/span-impl.js';
 import { NoopExporter } from '../observability/trace-exporter.js';
 import { createInMemoryFsAdapter, createInMemoryShellAdapter, createInMemorySubprocessAdapter, OpenRouter, } from './deps/adapters.js';
-import { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, completeLayers, contextToExecCtx, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from './deps/context.js';
-import { collectAllTools, deduplicateTools, dispatchStepThroughAdapter, execute, } from './deps/interpreter.js';
+import { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, completeLayers, contextToExecCtx, createContextCacheStore, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from './deps/context.js';
+import { collectAllTools, deduplicateTools, dispatchStepThroughAdapter, execute, prepareBandedView, } from './deps/interpreter.js';
 import { buildItemStream, ChannelStore, ContextImpl, captureCheckpoint, clearCheckpoint, collectContextTree, createInMemoryStorage, createStepLedgerStore, filterReasoningStream, filterTextStream, resolveStepLedgerRetention, restoreFromCheckpoint, SessionRunner, StepLedger, snapshotCwdState, } from './deps/runtime.js';
 import { SteeringAction } from './deps/types.js';
 import { AgentHarnessModelCaller } from './model-call.js';
@@ -77,7 +77,43 @@ export function resolveLlmClient(config, env) {
         cache: config?.cache ?? false,
     };
 }
-function createClient(config) {
+/**
+ * Ask the provider to cache the prompt prefix.
+ *
+ * Anthropic caching is opt-in — without a breakpoint it caches nothing however
+ * stable the prefix is, measured against live models. OpenRouter accepts a
+ * `cache_control` directive on the request and places the breakpoints itself;
+ * providers that cache on their own (OpenAI, Gemini) ignore it.
+ *
+ * It has to be injected here rather than passed with the other request fields:
+ * the SDK validates the request against a generated schema that drops keys it
+ * does not know, and `cache_control` is one of them.
+ */
+async function addCacheBreakpoint(request) {
+    const body = await request.clone().text();
+    if (!body) {
+        return request;
+    }
+    let payload;
+    try {
+        payload = JSON.parse(body);
+    }
+    catch {
+        return request;
+    }
+    if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+        return request;
+    }
+    return new Request(request, {
+        body: JSON.stringify({
+            ...payload,
+            cache_control: {
+                type: 'ephemeral',
+            },
+        }),
+    });
+}
+function createClient(config, contextCache) {
     const resolved = resolveLlmClient(config, readLlmEnv());
     if (!resolved) {
         return undefined;
@@ -88,20 +124,25 @@ function createClient(config) {
     if (resolved.serverURL) {
         options.serverURL = resolved.serverURL;
     }
-    if (resolved.cache) {
-        // Inject `X-OpenRouter-Cache: true` on every request so the upstream serves
-        // identical model calls from cache without re-billing (deterministic re-runs).
-        return new OpenRouter({
-            ...options,
-            hooks: {
-                beforeRequest: (_ctx, request) => {
+    // A cache write costs more than a plain read, so the breakpoint only pays off
+    // when something is holding the prefix still — which is what anchoring does.
+    const wantsBreakpoint = contextCache?.enabled !== false;
+    if (!resolved.cache && !wantsBreakpoint) {
+        return new OpenRouter(options);
+    }
+    return new OpenRouter({
+        ...options,
+        hooks: {
+            beforeRequest: async (_ctx, request) => {
+                if (resolved.cache) {
+                    // Serve identical model calls from OpenRouter's own response cache
+                    // without re-billing (deterministic re-runs).
                     request.headers.set('X-OpenRouter-Cache', 'true');
-                    return request;
-                },
+                }
+                return wantsBreakpoint ? addCacheBreakpoint(request) : request;
             },
-        });
-    }
-    return new OpenRouter(options);
+        },
+    });
 }
 //#region AgentHarness
 /**
@@ -162,6 +203,8 @@ export class AgentHarness {
     layerStateStore;
     /** Per-harness memoization cache for `recallMode: 'eventual'` layers. */
     recallCache;
+    /** Per-harness pinned anchor output and epoch bookkeeping, keyed by cache lineage. */
+    contextCache;
     /**
      * Execution ids whose layer `init` hooks have already run, so repeated/nested
      * `run()` calls and the session turn path never re-init (which would clobber
@@ -191,6 +234,7 @@ export class AgentHarness {
             strictItemSchemas: opts.strictItemSchemas ?? true,
             projection: opts.projection,
             forceAtomicRecall: opts.forceAtomicRecall,
+            contextCache: opts.contextCache,
         };
         this.fs = opts.fs ?? createInMemoryFsAdapter();
         this.shell = opts.shell ?? createInMemoryShellAdapter();
@@ -206,7 +250,7 @@ export class AgentHarness {
         this.harnessTools = opts.tools ?? [];
         this._contextLayers = resolveContextOption(opts);
         this.callModelOverride = opts._testCallModel;
-        this.client = opts._testCallModel ? undefined : createClient(opts.llm);
+        this.client = opts._testCallModel ? undefined : createClient(opts.llm, opts.contextCache);
         this.channelStore = new ChannelStore();
         this.traceExporter = opts.traceExporter ?? new NoopExporter();
         this.layerStateStore =
@@ -215,6 +259,7 @@ export class AgentHarness {
                     console.warn(`[noetic] context layer '${layerId}' ${hook} error:`, error);
                 });
         this.recallCache = createRecallCache();
+        this.contextCache = createContextCacheStore();
         this.defaultDeliveryMode = opts.defaultDeliveryMode ?? 'next-turn';
         this.streamIdleTimeoutMs = opts.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS;
         this.itemSchemas = new ItemSchemaRegistry(opts.itemSchemas, {
@@ -660,14 +705,32 @@ export class AgentHarness {
         try {
             await this.ensureLayersInit(ctx);
             const recallResults = await this.recallLayers(layers, '', ctx);
-            const layerOutputItems = recallResults.flatMap((r) => r.items);
-            if (layerOutputItems.length === 0) {
+            // Band the output the way a real turn would, but read-only: a preview
+            // must not pin, count churn, or age the epoch, or looking at a
+            // conversation would change what the next turn sends.
+            const banded = await prepareBandedView({
+                recallResults,
+                layers,
+                execCtx: contextToExecCtx(ctx),
+                store: this.contextCache,
+                config: this.config.contextCache,
+                instructions: undefined,
+                policy: this.config.projection ?? DEFAULT_PROJECTION,
+                systemPromptItems: [],
+                budgets: new Map(),
+                readOnly: true,
+            });
+            if (banded.anchorItems.length === 0 &&
+                banded.liveItems.length === 0 &&
+                banded.deltaItems.length === 0) {
                 return historyItems;
             }
             return assembleView({
                 systemPromptItems: [],
-                layerOutputItems,
+                layerOutputItems: banded.anchorItems,
                 historyItems,
+                liveLayerItems: banded.liveItems,
+                deltaItems: banded.deltaItems,
             });
         }
         finally {

package/dist/harness/deps/context.d.ts

@@ -1,2 +1,2 @@
 export type { LayerStateStore, RecallCache } from '@noetic-tools/context';
-export { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, completeLayers, contextToExecCtx, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from '@noetic-tools/context';
+export { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, completeLayers, contextToExecCtx, createContextCacheStore, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from '@noetic-tools/context';

package/dist/harness/deps/context.js

@@ -1 +1 @@
-export { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, completeLayers, contextToExecCtx, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from '@noetic-tools/context';
+export { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, completeLayers, contextToExecCtx, createContextCacheStore, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from '@noetic-tools/context';

package/dist/harness/deps/interpreter.d.ts

@@ -1,4 +1,5 @@
 export { collectAllTools, deduplicateTools } from '../../interpreter/collect-tools.js';
+export { prepareBandedView } from '../../interpreter/context-assembly.js';
 export { execute } from '../../interpreter/execute.js';
 export type { DetachedSpawnOverrides } from '../../interpreter/step-dispatcher.js';
 export { dispatchStepThroughAdapter } from '../../interpreter/step-dispatcher.js';

package/dist/harness/deps/interpreter.js

@@ -1,4 +1,5 @@
 export { collectAllTools, deduplicateTools } from '../../interpreter/collect-tools.js';
+export { prepareBandedView } from '../../interpreter/context-assembly.js';
 export { execute } from '../../interpreter/execute.js';
 export { dispatchStepThroughAdapter } from '../../interpreter/step-dispatcher.js';
 export { isFunctionCall } from '../../interpreter/typeguards.js';

package/dist/harness/deps/types.d.ts

@@ -1,4 +1,4 @@
-export type { ContextData, ContextLayer, ExecutionContext, ProjectionPolicy, StorageAdapter, } from '@noetic-tools/context';
+export type { ContextCacheConfig, ContextCacheStore, ContextData, ContextLayer, ExecutionContext, ProjectionPolicy, StorageAdapter, } from '@noetic-tools/context';
 export type { AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, Channel, ChannelHandle, Context, CwdState, DeliveryMode, DetachedHandle, ExecuteInput, ExecuteOptions, ExternalChannel, FsAdapter, HarnessResponse, HarnessStatus, Item, ItemSchemaExtensions, LLMResponse, LlmProviderConfig, RecallLayerOutput, SessionScope, ShellAdapter, Span, SteeringDecision, Step, StreamEvent, StreamingItem, SubHarnessSession, SubprocessAdapter, Tool, TraceExporter, } from '@noetic-tools/types';
 export { SteeringAction } from '@noetic-tools/types';
 export type { ZodType } from 'zod';

package/dist/harness/model-call.js

@@ -272,6 +272,12 @@ class CallSpanCollector {
     finishModelSpan(span, usage, cost) {
         span.setAttribute(GenAI.USAGE_INPUT_TOKENS, usage.inputTokens);
         span.setAttribute(GenAI.USAGE_OUTPUT_TOKENS, usage.outputTokens);
+        if (usage.cachedTokens !== undefined) {
+            span.setAttribute(GenAI.USAGE_CACHED_INPUT_TOKENS, usage.cachedTokens);
+        }
+        if (usage.cacheWriteTokens !== undefined) {
+            span.setAttribute(GenAI.USAGE_CACHE_WRITE_TOKENS, usage.cacheWriteTokens);
+        }
         if (cost !== undefined) {
             span.setAttribute(GenAI.COST, cost);
         }
@@ -372,6 +378,10 @@ export class AgentHarnessModelCaller {
             outputTokens: 0,
             cachedTokens: 0,
         };
+        // Rounds after the first replay the same prefix and so hit the prompt cache
+        // whatever the first round did. Keep them apart: only round 0 says whether
+        // the assembled view was cached (see `noteCacheOutcome`).
+        const rounds = [];
         let totalCost = 0;
         const conversationInput = itemsToInput(prepared.remaining);
         const textFormat = request.outputSchema ? buildTextFormat(request.outputSchema) : undefined;
@@ -503,10 +513,8 @@ export class AgentHarnessModelCaller {
             });
             const roundUsage = extractUsage(sdkResponse.usage);
             const roundCost = sdkResponse.usage?.cost ?? 0;
-            spans.finishModelSpan(modelSpan, {
-                inputTokens: roundUsage.inputTokens,
-                outputTokens: roundUsage.outputTokens,
-            }, roundCost > 0 ? roundCost : undefined);
+            spans.finishModelSpan(modelSpan, roundUsage, roundCost > 0 ? roundCost : undefined);
+            rounds.push(roundUsage);
             totalUsage.inputTokens += roundUsage.inputTokens;
             totalUsage.outputTokens += roundUsage.outputTokens;
             totalUsage.cachedTokens += roundUsage.cachedTokens ?? 0;
@@ -539,7 +547,16 @@ export class AgentHarnessModelCaller {
         }
         return {
             items: allItems,
-            usage: totalUsage,
+            usage: {
+                inputTokens: totalUsage.inputTokens,
+                outputTokens: totalUsage.outputTokens,
+                // Stay `undefined` when no round reported a figure, so callers can tell
+                // "this provider says nothing about caching" from "nothing was cached".
+                cachedTokens: rounds.some((r) => r.cachedTokens !== undefined)
+                    ? totalUsage.cachedTokens
+                    : undefined,
+            },
+            rounds,
             cost: totalCost > 0 ? totalCost : undefined,
         };
     }

package/dist/index.d.ts

@@ -113,13 +113,13 @@ export { MergeStrategySchema, UntilPredicateSchema, validateWorkflow, WorkflowDo
 export type { Channel, ChannelHandle, ExternalChannel } from '@noetic-tools/types';
 /** @public */
 /** @public */
-export type { LLMResponse, LlmProviderConfig, ModelParams, RetryPolicy, ServerToolSpec, StepMeta, TokenUsage, Tool, ToolContextDeclaration, } from '@noetic-tools/types';
+export type { LLMResponse, LlmProviderConfig, ModelParams, RetryPolicy, RoundUsage, ServerToolSpec, StepMeta, TokenUsage, Tool, ToolContextDeclaration, } from '@noetic-tools/types';
 /** @public */
 export { isServerToolSpec } from '@noetic-tools/types';
 /** @public */
 /** @public */
 /** @public */
-export type { Context, ContextHarness, CwdState, ItemLog, LastLayerUsage, LayerUsageEntry, RestoreContextOptions, } from '@noetic-tools/types';
+export type { Context, ContextHarness, CwdState, EpochUsage, ItemLog, LastLayerUsage, LayerUsageEntry, RestoreContextOptions, } from '@noetic-tools/types';
 /** @public */
 export { getToolCwd, setToolCwd, snapshotCwdState } from './runtime/cwd-helpers.js';
 /** @public */
@@ -137,7 +137,7 @@ export type { NoeticError } from '@noetic-tools/types';
 /** @public */
 export type { ContentPart, DeveloperMessageExtensionItem, ExecuteInput, ExtendedItem, ExtensionItem, FileSearchItem, FunctionCallItem, FunctionCallOutputItem, ImageGenerationItem, InferExtendedItem, InputContentPart, InputFilePart, InputImagePart, InputMessageItem, InputTextPart, Item, ItemBase, ItemSchemaExtensions, MessageItem, OutputItem, OutputTextPart, ReasoningItem, ReasoningTextPart, RefusalPart, ServerToolItem, SummaryTextPart, WebSearchItem, } from '@noetic-tools/types';
 /** @public */
-export type { BudgetConfig, CompleteParams, ContextConfig, ContextData, ContextLayer, ContextLayerHooks, DisposeParams, InferContext, InferContextShape, InitParams, InitResult, LayerDataDecl, LayerFunctionDecl, LayerProvides, LayerTimeouts, ProjectionPolicy, RecallParams, RecallResult, ReturnParams, ReturnResult, ScopedStorage, SpawnParams, SpawnResult, StorageAdapter, StoreParams, StoreResult, } from '@noetic-tools/context';
+export type { BudgetConfig, CompleteParams, ContextConfig, ContextData, ContextLayer, ContextLayerHooks, DisposeParams, InferContext, InferContextShape, InitParams, InitResult, LayerDataDecl, LayerFunctionDecl, LayerPlacement, LayerProvides, LayerTimeouts, ProjectionPolicy, RecallParams, RecallResult, RenderDeltaParams, ReturnParams, ReturnResult, ScopedStorage, SpawnParams, SpawnResult, StorageAdapter, StoreParams, StoreResult, } from '@noetic-tools/context';
 /** @public */
 export { Slot } from '@noetic-tools/context';
 /** @public */
@@ -147,7 +147,7 @@ export type { LayerTraceSpan, Span, TraceExporter } from '@noetic-tools/types';
 /** @public */
 export type { FrameworkStreamEvent, HarnessResponse, SdkStreamEvent, StreamEvent, StreamingItem, } from '@noetic-tools/types';
 /** @public */
-export type { AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, DeliveryMode, ExecuteOptions, HarnessStatus, RecallLayerOutput, SessionScope, } from '@noetic-tools/types';
+export type { AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, ContextCacheConfig, ContextCacheStore, ContextEpoch, DeliveryMode, ExecuteOptions, HarnessStatus, ReanchorReason, RecallLayerOutput, SessionScope, } from '@noetic-tools/types';
 /** @public */
 export type { AfterModelCallParams, AfterModelCallResult, BeforeToolCallParams, BeforeToolCallResult, LedgerEntry, SteeringConfig, SteeringDecision, SteeringRule, SteeringState, } from '@noetic-tools/types';
 /** @public */

package/dist/interpreter/action-deps.d.ts

@@ -1,5 +1,5 @@
-export type { LayerStateStore } from '@noetic-tools/context';
-export { allocateBudgets, assembleView, commitLayerUsage, computeLayerUsage, contextToExecCtx, DEFAULT_PROJECTION, resolveLayerTools, returnLayers, spawnLayers, } from '@noetic-tools/context';
+export type { LayerServeInfo, LayerStateStore } from '@noetic-tools/context';
+export { allocateBudgets, assembleView, churnFor, churnRate, commitLayerUsage, computeLayerUsage, contextToExecCtx, createContextCacheStore, DEFAULT_PROJECTION, lineageKey, noteCacheOutcome, openEpoch, pin, pinKey, reanchorReason, resolveCacheConfig, resolveLayerTools, returnLayers, spawnLayers, } from '@noetic-tools/context';
 export type { ItemSchemaRegistry } from '@noetic-tools/types';
 export { defaultItemSchemaRegistry } from '@noetic-tools/types';
 export { emitFrameworkEvent, getBroadcaster, shouldEmit } from '../runtime/broadcaster-utils.js';

package/dist/interpreter/action-deps.js

@@ -1,4 +1,4 @@
-export { allocateBudgets, assembleView, commitLayerUsage, computeLayerUsage, contextToExecCtx, DEFAULT_PROJECTION, resolveLayerTools, returnLayers, spawnLayers, } from '@noetic-tools/context';
+export { allocateBudgets, assembleView, churnFor, churnRate, commitLayerUsage, computeLayerUsage, contextToExecCtx, createContextCacheStore, DEFAULT_PROJECTION, lineageKey, noteCacheOutcome, openEpoch, pin, pinKey, reanchorReason, resolveCacheConfig, resolveLayerTools, returnLayers, spawnLayers, } from '@noetic-tools/context';
 export { defaultItemSchemaRegistry } from '@noetic-tools/types';
 export { emitFrameworkEvent, getBroadcaster, shouldEmit } from '../runtime/broadcaster-utils.js';
 export { ContextImpl } from '../runtime/context-impl.js';

package/dist/interpreter/action-types.d.ts

@@ -1,3 +1,3 @@
 export type { ContextConfig, ContextData, ContextLayer, ExecutionContext, } from '@noetic-tools/context';
-export type { AgentHarnessContract, Context, ContextRerenderRequest, ExecuteStepFn, FunctionCallItem, Item, ProjectionPolicy, RecallLayerOutput, RetryPolicy, ServerToolSpec, StepLLM, StepMeta, StepProvide, StepRun, StepSpawn, StepTool, Tool, } from '@noetic-tools/types';
+export type { AgentHarnessContract, Context, ContextRerenderRequest, ExecuteStepFn, FunctionCallItem, InputMessageItem, Item, ProjectionPolicy, RecallLayerOutput, RetryPolicy, ServerToolSpec, StepLLM, StepMeta, StepProvide, StepRun, StepSpawn, StepTool, Tool, } from '@noetic-tools/types';
 export { isServerToolSpec, SteeringAction } from '@noetic-tools/types';

package/dist/interpreter/context-assembly.d.ts

@@ -0,0 +1,50 @@
+import type { ContextCacheConfig, ContextCacheStore, ContextLayer, EpochUsage, ExecutionContext, Item, ProjectionPolicy, RecallLayerOutput, Span } from '@noetic-tools/types';
+import type { LayerServeInfo } from './action-deps.js';
+/** What the layer bands contributed to one assembly, and how the epoch fared. */
+export interface BandedView {
+    /** Layer output rendered before history — pinned bytes where a pin exists. */
+    anchorItems: Item[];
+    /** Layer output rendered after history. */
+    liveItems: Item[];
+    /** At most one developer message superseding stale anchors. */
+    deltaItems: Item[];
+    /** Per-layer output as actually served, for the usage breakdown. */
+    servedPerLayer: RecallLayerOutput[];
+    serveInfo: Map<string, LayerServeInfo>;
+    epoch: EpochUsage | undefined;
+}
+interface PrepareBandedViewParams {
+    /** Recall output, already slot-sorted and merged with any re-render. */
+    recallResults: ReadonlyArray<RecallLayerOutput>;
+    layers: ReadonlyArray<ContextLayer>;
+    execCtx: ExecutionContext;
+    store: ContextCacheStore;
+    config?: ContextCacheConfig;
+    /** Resolved instructions — a change to them invalidates the prefix anyway. */
+    instructions: string | undefined;
+    policy: ProjectionPolicy;
+    systemPromptItems: ReadonlyArray<Item>;
+    /** Budget per layer id, used to size a `renderDelta`. */
+    budgets: ReadonlyMap<string, number>;
+    /**
+     * When true, read pins without writing: no new pins, no churn, no epoch
+     * ageing. For preview paths that must not disturb a live conversation.
+     */
+    readOnly?: boolean;
+}
+/**
+ * Split recall output into the anchor and live bands, replay pinned anchors, and
+ * gather everything that changed into a single supersede message.
+ *
+ * Runs once per LLM step, before the steering retry loop — a retry replays the
+ * same view, so re-pinning or re-counting churn there would distort both.
+ */
+export declare function prepareBandedView(params: PrepareBandedViewParams): Promise<BandedView>;
+/**
+ * Record how the view was banded on the step's span, so a slow or expensive run
+ * can be traced back to the layer that keeps invalidating the prefix.
+ */
+export declare function stampAnchoringAttributes(span: Span | undefined, view: BandedView): void;
+/** Tokens the prompt prefix was expected to have cached — what `noteCacheOutcome` judges against. */
+export declare function expectedCachedTokens(systemPromptItems: ReadonlyArray<Item>, view: BandedView): number;
+export {};

package/dist/interpreter/context-assembly.js

@@ -0,0 +1,547 @@
+import { createMessage, estimateTokens, hashItems, hashString } from '@noetic-tools/types';
+import { NoeticAttr } from '../observability/genai-attributes.js';
+import { churnFor, churnRate, lineageKey, openEpoch, pin, pinKey, reanchorReason, resolveCacheConfig, } from './action-deps.js';
+/**
+ * Supersedes below this are never treated as delta pressure, whatever share of
+ * the anchor band they are. Keeps a small context from re-anchoring on the fixed
+ * cost of the `<context_updates>` wrapper alone.
+ */
+const MIN_PRESSURE_TOKENS = 256;
+//#endregion
+//#region Public API
+/**
+ * Split recall output into the anchor and live bands, replay pinned anchors, and
+ * gather everything that changed into a single supersede message.
+ *
+ * Runs once per LLM step, before the steering retry loop — a retry replays the
+ * same view, so re-pinning or re-counting churn there would distort both.
+ */
+export async function prepareBandedView(params) {
+    const config = resolveCacheConfig(params.config);
+    if (!config.enabled) {
+        return legacyView(params.recallResults);
+    }
+    const key = lineageKey(params.execCtx);
+    const instructionsHash = hashString(params.instructions ?? '');
+    const epoch = resolveEpoch({
+        ...params,
+        config,
+        key,
+        instructionsHash,
+    });
+    const banded = bandAndPin({
+        ...params,
+        config,
+        epoch,
+    });
+    const anchorTokens = totalTokens(banded.anchorItems);
+    const rendered = await buildDeltaItems(banded.stale, epoch.id, params.execCtx);
+    // A change we cannot put into words must not be published as silence: the
+    // pinned block is already in the view and the model would read it as current.
+    // Re-anchor so the fresh render reaches it directly instead.
+    const undescribed = rendered.undescribed;
+    // Two ways the supersedes stop being worth their tokens: they outgrow the
+    // band they patch, or they no longer fit the window at all. Either way the
+    // answer is the same — re-anchor to fresh output and publish nothing. That
+    // costs one cache miss and never risks shipping content known to be stale.
+    //
+    // The ratio alone is not enough: the wrapper around a supersede costs a fixed
+    // few dozen tokens, which would always look enormous beside a small anchor
+    // band and re-anchor every turn. Pressure needs the supersedes to be both
+    // absolutely and proportionally large.
+    const deltaTokens = totalTokens(rendered.items);
+    const overPressure = deltaTokens > Math.max(MIN_PRESSURE_TOKENS, config.deltaBudgetFraction * anchorTokens);
+    if (!params.readOnly && (undescribed || overPressure)) {
+        return rebuildOnFreshEpoch({
+            ...params,
+            config,
+            key,
+            instructionsHash,
+            reason: overPressure ? 'delta-pressure' : 'delta-overflow',
+        });
+    }
+    if (!params.readOnly) {
+        epoch.anchorTokens = anchorTokens;
+        epoch.assemblies += 1;
+        epoch.deltaTokens = deltaTokens;
+    }
+    const deltaItems = rendered.items;
+    return {
+        anchorItems: banded.anchorItems,
+        liveItems: banded.liveItems,
+        deltaItems,
+        servedPerLayer: banded.servedPerLayer,
+        serveInfo: banded.serveInfo,
+        epoch: summarize(epoch, banded.liveTokens, deltaTokens),
+    };
+}
+/**
+ * Record how the view was banded on the step's span, so a slow or expensive run
+ * can be traced back to the layer that keeps invalidating the prefix.
+ */
+export function stampAnchoringAttributes(span, view) {
+    if (!span || !view.epoch) {
+        return;
+    }
+    const { epoch } = view;
+    span.setAttribute(NoeticAttr.CONTEXT_EPOCH_ID, epoch.id);
+    span.setAttribute(NoeticAttr.CONTEXT_EPOCH_AGE, epoch.age);
+    span.setAttribute(NoeticAttr.CONTEXT_ANCHOR_TOKENS, epoch.anchorTokens);
+    span.setAttribute(NoeticAttr.CONTEXT_LIVE_TOKENS, epoch.liveTokens);
+    span.setAttribute(NoeticAttr.CONTEXT_DELTA_TOKENS, epoch.deltaTokens);
+    if (epoch.reanchorReason) {
+        span.setAttribute(NoeticAttr.CONTEXT_REANCHOR_REASON, epoch.reanchorReason);
+    }
+    if (view.serveInfo.size === 0) {
+        return;
+    }
+    const placements = [];
+    const churn = [];
+    for (const [id, info] of view.serveInfo) {
+        placements.push({
+            id,
+            placement: info.placement,
+            served: info.served,
+            changed: info.changed,
+        });
+        churn.push({
+            id,
+            rate: Number(info.churnRate.toFixed(3)),
+            rebillTokens: Math.round(info.rebillTokens),
+        });
+    }
+    // Span attributes hold only scalars, so structured values travel as JSON.
+    span.setAttribute(NoeticAttr.CONTEXT_LAYER_PLACEMENTS, JSON.stringify(placements));
+    span.setAttribute(NoeticAttr.CONTEXT_LAYER_CHURN, JSON.stringify(churn));
+}
+/** Tokens the prompt prefix was expected to have cached — what `noteCacheOutcome` judges against. */
+export function expectedCachedTokens(systemPromptItems, view) {
+    return totalTokens(systemPromptItems) + (view.epoch?.anchorTokens ?? 0);
+}
+//#endregion
+//#region Epoch resolution
+function resolveEpoch(params) {
+    const { store, key, instructionsHash, config } = params;
+    const current = store.epochs.get(key);
+    const reason = reanchorReason({
+        epoch: current,
+        key,
+        instructionsHash,
+        store,
+        config,
+    });
+    // A read-only pass never opens or rebuilds an epoch — looking at a
+    // conversation must not change what its next turn sends. It reuses whatever
+    // exists, or works against a throwaway when the lineage is still cold.
+    if (params.readOnly) {
+        return current ?? emptyEpoch(key, instructionsHash);
+    }
+    if (!reason) {
+        // No reason fires while `current` is absent — that case is 'cold-start'.
+        return current ?? emptyEpoch(key, instructionsHash);
+    }
+    return openEpoch({
+        store,
+        key,
+        reason,
+        instructionsHash,
+        layers: params.layers,
+        config,
+    });
+}
+/** Re-anchor and band again, publishing no supersedes against the fresh pins. */
+async function rebuildOnFreshEpoch(params) {
+    const epoch = openEpoch({
+        store: params.store,
+        key: params.key,
+        reason: params.reason,
+        instructionsHash: params.instructionsHash,
+        layers: params.layers,
+        config: params.config,
+    });
+    const banded = bandAndPin({
+        ...params,
+        epoch,
+    });
+    epoch.anchorTokens = totalTokens(banded.anchorItems);
+    epoch.assemblies += 1;
+    epoch.deltaTokens = 0;
+    return {
+        anchorItems: banded.anchorItems,
+        liveItems: banded.liveItems,
+        deltaItems: [],
+        servedPerLayer: banded.servedPerLayer,
+        serveInfo: banded.serveInfo,
+        epoch: summarize(epoch, banded.liveTokens, 0),
+    };
+}
+/**
+ * Place each layer's output in a band, then build the anchor band from the pins
+ * themselves rather than from this turn's recall.
+ *
+ * Serving the pin map — in pin insertion order, which is the slot order of the
+ * assembly that anchored it — is what makes the prefix byte-stable by
+ * construction. Nothing a later turn does (a layer falling silent, a new layer
+ * appearing, a layer turning non-idempotent) can reorder or shorten it; those
+ * all become supersedes at the tail instead.
+ */
+function bandAndPin(params) {
+    const { epoch, store, layers, budgets, readOnly } = params;
+    const byId = new Map(layers.map((l) => [
+        l.id,
+        l,
+    ]));
+    const out = {
+        anchorItems: [],
+        liveItems: [],
+        liveTokens: 0,
+        servedPerLayer: [],
+        serveInfo: new Map(),
+        stale: [],
+    };
+    const anchored = new Map();
+    for (const result of params.recallResults) {
+        const layer = byId.get(result.layerId);
+        // Output from a layer that is not in this step's set can never be pinned
+        // against it; render it live rather than guessing.
+        if (!layer || bandFor(layer, result, epoch) === 'live') {
+            out.liveItems.push(...result.items);
+            out.liveTokens += result.tokenCount;
+            out.servedPerLayer.push(result);
+            if (layer) {
+                out.serveInfo.set(layer.id, {
+                    placement: 'live',
+                    served: 'fresh',
+                    changed: false,
+                    churnRate: churnRate(churnFor(store, pinKey(layer))),
+                    rebillTokens: 0,
+                });
+            }
+            continue;
+        }
+        anchored.set(pinKey(layer), result);
+    }
+    // A fresh epoch anchors whatever it is given, in slot order. A read-only pass
+    // does the same but keeps the result to itself, so a preview still shows the
+    // view the next real turn would send without deciding it in advance.
+    const pins = epoch.pins.size > 0 || epoch.assemblies > 0 ? epoch.pins : new Map();
+    if (pins !== epoch.pins) {
+        for (const [key, result] of anchored) {
+            const layer = byId.get(result.layerId);
+            if (!layer) {
+                continue;
+            }
+            const entry = {
+                layerId: layer.id,
+                items: result.items,
+                tokenCount: result.tokenCount,
+                contentHash: hashItems(result.items),
+                state: undefined,
+                slot: layer.slot,
+            };
+            pins.set(key, entry);
+            if (!readOnly) {
+                pin(epoch, key, entry);
+            }
+        }
+    }
+    servePins({
+        out,
+        epoch,
+        pins,
+        anchored,
+        byId,
+        store,
+        budgets,
+        readOnly: readOnly === true,
+    });
+    collectAdditions({
+        out,
+        pins,
+        anchored,
+        byId,
+        store,
+        budgets,
+        readOnly: readOnly === true,
+    });
+    return out;
+}
+/**
+ * An explicit placement always wins. A layer whose `recall` changed state is
+ * forced live regardless: replaying an older render would discard the very
+ * thing that call committed.
+ */
+function bandFor(layer, result, epoch) {
+    if (result.mutatedState) {
+        return 'live';
+    }
+    if (layer.placement === 'anchor' || layer.placement === 'live') {
+        return layer.placement;
+    }
+    return epoch.autoBand.get(pinKey(layer)) ?? 'anchor';
+}
+/**
+ * Serve every pin, in pinned order, and note which have gone stale.
+ *
+ * A pin is served even when its layer produced nothing this turn, or has since
+ * moved to the live band: dropping it would shorten the prefix and cost the
+ * cache far more than the tokens it saves. The model is told to disregard it
+ * instead, every turn, until the next re-anchor clears it.
+ */
+function servePins(args) {
+    const { out, epoch, pins, anchored, byId, store, budgets, readOnly } = args;
+    for (const [key, held] of pins) {
+        out.anchorItems.push(...held.items);
+        const layer = byId.get(held.layerId);
+        const fresh = anchored.get(key);
+        const churn = churnFor(store, key);
+        // The pin is what the model sees, changed or not — that is the whole point.
+        out.servedPerLayer.push({
+            layerId: held.layerId,
+            items: held.items,
+            tokenCount: held.tokenCount,
+        });
+        if (!fresh || !layer) {
+            // Gone quiet, or moved to the live band. Either way the pinned block no
+            // longer reflects reality and must carry a standing retraction.
+            if (layer) {
+                out.stale.push({
+                    layer,
+                    action: 'retract',
+                    prev: held.items,
+                    next: [],
+                    prevState: held.state,
+                    budget: budgets.get(layer.id) ?? 0,
+                });
+                out.serveInfo.set(layer.id, {
+                    placement: 'anchor',
+                    served: 'pinned',
+                    changed: true,
+                    churnRate: churnRate(churn),
+                    rebillTokens: churn.rebillTokens,
+                });
+            }
+            continue;
+        }
+        const changed = held.contentHash !== hashItems(fresh.items);
+        if (!readOnly) {
+            churn.observed += 1;
+            if (changed) {
+                churn.changed += 1;
+                churn.rebillTokens += epoch.anchorTokens;
+            }
+        }
+        if (changed) {
+            out.stale.push({
+                layer,
+                action: 'replace',
+                prev: held.items,
+                next: fresh.items,
+                prevState: held.state,
+                budget: budgets.get(layer.id) ?? 0,
+            });
+        }
+        out.serveInfo.set(layer.id, {
+            placement: 'anchor',
+            served: 'pinned',
+            changed,
+            churnRate: churnRate(churn),
+            rebillTokens: churn.rebillTokens,
+        });
+    }
+}
+/**
+ * Publish anchored output that has no pin — a layer first seen mid-epoch. It
+ * cannot be spliced into a frozen prefix, so it rides in the supersede message
+ * until the next re-anchor folds it into the band. Its tokens count toward
+ * delta pressure, so a run of additions re-anchors on its own.
+ */
+function collectAdditions(args) {
+    const { out, pins, anchored, byId, store, budgets, readOnly } = args;
+    for (const [key, result] of anchored) {
+        if (pins.has(key)) {
+            continue;
+        }
+        const layer = byId.get(result.layerId);
+        if (!layer) {
+            continue;
+        }
+        const churn = churnFor(store, key);
+        if (!readOnly) {
+            churn.observed += 1;
+            churn.changed += 1;
+        }
+        out.stale.push({
+            layer,
+            action: 'add',
+            prev: [],
+            next: result.items,
+            prevState: undefined,
+            budget: budgets.get(layer.id) ?? 0,
+        });
+        out.servedPerLayer.push(result);
+        out.serveInfo.set(layer.id, {
+            placement: 'anchor',
+            served: 'fresh',
+            changed: true,
+            churnRate: churnRate(churn),
+            rebillTokens: churn.rebillTokens,
+        });
+    }
+}
+//#endregion
+//#region Supersedes
+/**
+ * Render every stale anchor into ONE developer message.
+ *
+ * A layer may describe its own change compactly via `renderDelta`; otherwise the
+ * full new content is republished, which costs more tokens but is always right.
+ * A hook that throws or hangs falls back to the default — a supersede is a
+ * correctness obligation, so it is never skipped because a hook misbehaved.
+ */
+async function buildDeltaItems(stale, epochId, ctx) {
+    if (stale.length === 0) {
+        return {
+            items: [],
+            undescribed: false,
+        };
+    }
+    const blocks = [];
+    let undescribed = false;
+    for (const entry of stale) {
+        const body = await renderBody(entry, ctx);
+        if (body === null) {
+            // Nothing renderable — a layer emitting non-text items, say. The pinned
+            // block is already in the view, so staying silent would present it as
+            // current. Report it and let the caller re-anchor.
+            undescribed = true;
+            continue;
+        }
+        blocks.push(`<update layer="${entry.layer.id}" action="${entry.action}">\n${body}\n</update>`);
+    }
+    if (blocks.length === 0) {
+        return {
+            items: [],
+            undescribed,
+        };
+    }
+    const text = [
+        `<context_updates epoch="${epochId}">`,
+        'These supersede the blocks with the same layer id earlier in this context.',
+        'Where they disagree, these are correct.',
+        ...blocks,
+        '</context_updates>',
+    ].join('\n');
+    return {
+        items: [
+            createMessage(text, 'developer'),
+        ],
+        undescribed,
+    };
+}
+async function renderBody(entry, ctx) {
+    if (entry.action === 'retract') {
+        return 'This block no longer applies. Disregard it.';
+    }
+    const custom = await tryRenderDelta(entry, ctx);
+    if (custom !== null) {
+        return custom;
+    }
+    const full = itemsToText(entry.next);
+    if (full.length > 0) {
+        return full;
+    }
+    // A layer that rendered nothing this turn is saying its block is gone, which
+    // is a retraction however it was classified.
+    return entry.next.length === 0 ? 'This block no longer applies. Disregard it.' : null;
+}
+async function tryRenderDelta(entry, ctx) {
+    const hook = entry.layer.hooks.renderDelta;
+    if (!hook) {
+        return null;
+    }
+    try {
+        const timeout = entry.layer.timeouts?.recall ?? 5e3;
+        const rendered = await withTimeout(hook({
+            prev: entry.prev,
+            next: entry.next,
+            prevState: entry.prevState,
+            state: ctx.readLayerState(entry.layer.id),
+            ctx,
+            budget: entry.budget,
+        }), timeout);
+        return rendered && rendered.length > 0 ? rendered : null;
+    }
+    catch {
+        // Fall back to republishing in full — see `buildDeltaItems`.
+        return null;
+    }
+}
+function withTimeout(promise, ms) {
+    return Promise.race([
+        promise,
+        new Promise((_, reject) => setTimeout(() => reject(new Error('renderDelta timed out')), ms)),
+    ]);
+}
+//#endregion
+//#region Helpers
+/** Everything before history, as it was assembled before bands existed. */
+function legacyView(recallResults) {
+    return {
+        anchorItems: recallResults.flatMap((r) => r.items),
+        liveItems: [],
+        deltaItems: [],
+        servedPerLayer: [
+            ...recallResults,
+        ],
+        serveInfo: new Map(),
+        epoch: undefined,
+    };
+}
+/** A throwaway epoch for a read-only pass on a lineage that has none yet. */
+function emptyEpoch(key, instructionsHash) {
+    return {
+        id: `${key}#preview`,
+        pins: new Map(),
+        autoBand: new Map(),
+        instructionsHash,
+        assemblies: 0,
+        anchorTokens: 0,
+        deltaTokens: 0,
+        cacheBlind: false,
+        misses: 0,
+        lastReanchorReason: 'cold-start',
+    };
+}
+function summarize(epoch, liveTokens, deltaTokens) {
+    return {
+        id: epoch.id,
+        age: epoch.assemblies,
+        anchorTokens: epoch.anchorTokens,
+        liveTokens,
+        deltaTokens,
+        reanchorReason: epoch.assemblies <= 1 ? epoch.lastReanchorReason : undefined,
+    };
+}
+function itemsToText(items) {
+    const parts = [];
+    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') {
+                parts.push(part.text);
+            }
+        }
+    }
+    return parts.join('\n');
+}
+function totalTokens(items) {
+    let total = 0;
+    for (const item of items) {
+        total += estimateTokens(JSON.stringify(item));
+    }
+    return total;
+}
+//#endregion

package/dist/interpreter/execute-action.js

@@ -4,10 +4,11 @@
 import { createMessage, estimateTokens, extractAssistantText, frameworkCast, isNoeticError, isOutputCodec, NoeticConfigError, NoeticErrorImpl, } from '@noetic-tools/types';
 import { ZodError } from 'zod';
 import { emitToolUi } from '../runtime/tool-ui.js';
-import { allocateBudgets, assembleView, buildToolExecutionContext, ContextImpl, commitLayerUsage, computeLayerUsage, contextToExecCtx, DEFAULT_PROJECTION, defaultItemSchemaRegistry, emitFrameworkEvent, getBroadcaster, resolveLayerTools, returnLayers, shouldEmit, snapshotCwdState, spawnLayers, } from './action-deps.js';
+import { allocateBudgets, assembleView, buildToolExecutionContext, ContextImpl, commitLayerUsage, computeLayerUsage, contextToExecCtx, createContextCacheStore, DEFAULT_PROJECTION, defaultItemSchemaRegistry, emitFrameworkEvent, getBroadcaster, lineageKey, noteCacheOutcome, resolveCacheConfig, resolveLayerTools, returnLayers, shouldEmit, snapshotCwdState, spawnLayers, } from './action-deps.js';
 import { isServerToolSpec, SteeringAction } from './action-types.js';
 import { cloneWithGuard } from './clone-guard.js';
 import { collectAllTools, deduplicateTools } from './collect-tools.js';
+import { prepareBandedView, stampAnchoringAttributes } from './context-assembly.js';
 import { trackUsage } from './message-helpers.js';
 import { getContextChannelStore, isContextImpl, isFunctionCall, isMutableContext, } from './typeguards.js';
 //#region run
@@ -364,8 +365,31 @@ export async function executeLLM(step, input, ctx, layers) {
             ], rerendered, slotOf);
         }
     }
-    const layerOutputItems = recallResults.flatMap((r) => r.items);
+    // Split recall output into the cache-stable anchor band and the live band,
+    // replaying pinned anchors and gathering any changes into one supersede
+    // message. Runs once, outside the retry loop, for the same reason recall does:
+    // a retry replays this view rather than building a new one.
+    // A harness that predates anchoring carries no store. Give it a throwaway:
+    // nothing survives the turn, so its layers render fresh every time — the
+    // behaviour it had before the bands existed.
+    const cacheStore = baseCtx.harness.contextCache ?? createContextCacheStore();
+    const banded = await prepareBandedView({
+        recallResults,
+        layers: layers ?? [],
+        execCtx: contextToExecCtx(baseCtx),
+        store: cacheStore,
+        config: baseCtx.harness.config.contextCache,
+        instructions: resolvedInstructions,
+        policy: viewPolicy,
+        systemPromptItems: [],
+        budgets: budgetMap,
+    });
+    stampAnchoringAttributes(baseCtx.span, banded);
     let retries = 0;
+    // Guidance from a steering retry rides at the very end of the view, after the
+    // live band and the supersedes, rather than wherever history happens to put it.
+    let steeringTail = [];
+    let cacheJudged = false;
     while (retries <= MAX_STEERING_RETRIES) {
         const rawHistoryItems = baseCtx.itemLog.items;
         const projectedHistoryItems = hasLayers
@@ -377,17 +401,26 @@ export async function executeLLM(step, input, ctx, layers) {
             // budget (drops highest-slot layer output, then oldest history).
             const systemItems = [];
             const nonSystemHistory = [];
+            const tailIds = new Set(steeringTail.map((i) => i.id));
             for (const item of projectedHistoryItems) {
                 if (item.type === 'message' && item.role === 'system') {
                     systemItems.push(item);
                     continue;
                 }
+                // Steering guidance is re-placed at the tail; skip it here so the retry
+                // does not see the same correction twice.
+                if ('id' in item && typeof item.id === 'string' && tailIds.has(item.id)) {
+                    continue;
+                }
                 nonSystemHistory.push(item);
             }
             assembledItems = assembleView({
                 systemPromptItems: systemItems,
-                layerOutputItems,
+                layerOutputItems: banded.anchorItems,
                 historyItems: nonSystemHistory,
+                liveLayerItems: banded.liveItems,
+                deltaItems: banded.deltaItems,
+                tailItems: steeringTail,
                 policy: viewPolicy,
             });
         }
@@ -440,6 +473,23 @@ export async function executeLLM(step, input, ctx, layers) {
         // real, and until.maxCost / HarnessResponse.usage must see it (spec 07:
         // tokens accumulate across all LLM calls).
         trackUsage(baseCtx, response);
+        // Ask the model's own token report whether the prompt prefix survived. A
+        // clear miss records a re-anchor that the next assembly picks up — pins are
+        // never touched here, so a response steering later rejects cannot leave the
+        // epoch half-rebuilt.
+        // Judged once per assembly, not once per call: a steering retry re-sends
+        // the same view, so counting its response again would reach the give-up
+        // threshold inside a single turn and blind the lineage for good.
+        if (banded.epoch && !cacheJudged) {
+            cacheJudged = true;
+            noteCacheOutcome({
+                store: cacheStore,
+                key: lineageKey(contextToExecCtx(baseCtx)),
+                response,
+                config: resolveCacheConfig(baseCtx.harness.config.contextCache),
+                expectedTokens: systemPromptTokens + banded.epoch.anchorTokens,
+            });
+        }
         // An abort that landed mid-call returns whatever rounds completed before
         // the signal fired. The spend is charged above, but a truncated generation
         // is not this step's output — surface cancellation instead.
@@ -458,7 +508,16 @@ export async function executeLLM(step, input, ctx, layers) {
                 });
             }
             if (decision.action === SteeringAction.Guide && retries < MAX_STEERING_RETRIES) {
-                baseCtx.itemLog.append(createMessage(decision.guidance ?? 'Please adjust your response.', 'developer'));
+                const guidance = createMessage(decision.guidance ?? 'Please adjust your response.', 'developer');
+                // Logged so it persists into the conversation, and carried as the tail
+                // so the retry's view ends on the correction rather than burying it
+                // ahead of the live band. Assembly drops it from history to avoid
+                // showing it twice.
+                baseCtx.itemLog.append(guidance);
+                steeringTail = [
+                    ...steeringTail,
+                    guidance,
+                ];
                 retries++;
                 continue;
             }
@@ -484,7 +543,11 @@ export async function executeLLM(step, input, ctx, layers) {
             modelId: resolvedModel,
             instructions: resolvedInstructions,
             tools: resolvedTools,
-            recallResults,
+            // What the model was actually shown, pinned replays included — raw
+            // recall output would report content it never saw.
+            recallResults: banded.servedPerLayer,
+            serveInfo: banded.serveInfo,
+            epoch: banded.epoch,
         }));
         if (hasLayers) {
             await baseCtx.harness.storeLayers(layers, response, baseCtx);

package/dist/observability/genai-attributes.d.ts

@@ -3,6 +3,10 @@ export declare const GenAI: {
     readonly REQUEST_MODEL: 'gen_ai.request.model';
     readonly USAGE_INPUT_TOKENS: 'gen_ai.usage.input_tokens';
     readonly USAGE_OUTPUT_TOKENS: 'gen_ai.usage.output_tokens';
+    /** Prompt tokens served from the provider's cache. Absent if unreported. */
+    readonly USAGE_CACHED_INPUT_TOKENS: 'gen_ai.usage.cached_input_tokens';
+    /** Prompt tokens written into the provider's cache. Absent if unreported. */
+    readonly USAGE_CACHE_WRITE_TOKENS: 'gen_ai.usage.cache_write_tokens';
     readonly COST: 'gen_ai.cost';
 };
 export declare const ToolAttr: {
@@ -30,4 +34,20 @@ export declare const NoeticAttr: {
     readonly SESSION_ID: 'noetic.session.id';
     /** Resource the session is scoped to (the run's `ctx.resourceId`), when set. */
     readonly RESOURCE_ID: 'noetic.resource.id';
+    /** Id of the anchoring epoch the assembled view belongs to. */
+    readonly CONTEXT_EPOCH_ID: 'noetic.context.epoch.id';
+    /** Assemblies served by the current epoch, including this one. */
+    readonly CONTEXT_EPOCH_AGE: 'noetic.context.epoch.age';
+    /** Why the epoch re-anchored on this assembly, when it did. */
+    readonly CONTEXT_REANCHOR_REASON: 'noetic.context.reanchor_reason';
+    /** Tokens in the anchor band (the cache-stable prefix). */
+    readonly CONTEXT_ANCHOR_TOKENS: 'noetic.context.anchor_tokens';
+    /** Tokens in the live band (rendered after history). */
+    readonly CONTEXT_LIVE_TOKENS: 'noetic.context.live_tokens';
+    /** Tokens spent superseding stale anchors. */
+    readonly CONTEXT_DELTA_TOKENS: 'noetic.context.delta_tokens';
+    /** JSON array of `{ id, placement, served }` per contributing layer. */
+    readonly CONTEXT_LAYER_PLACEMENTS: 'noetic.context.layer_placements';
+    /** JSON array of `{ id, rate, rebillTokens }` per contributing layer. */
+    readonly CONTEXT_LAYER_CHURN: 'noetic.context.layer_churn';
 };

package/dist/observability/genai-attributes.js

@@ -4,6 +4,10 @@ export const GenAI = {
     REQUEST_MODEL: 'gen_ai.request.model',
     USAGE_INPUT_TOKENS: 'gen_ai.usage.input_tokens',
     USAGE_OUTPUT_TOKENS: 'gen_ai.usage.output_tokens',
+    /** Prompt tokens served from the provider's cache. Absent if unreported. */
+    USAGE_CACHED_INPUT_TOKENS: 'gen_ai.usage.cached_input_tokens',
+    /** Prompt tokens written into the provider's cache. Absent if unreported. */
+    USAGE_CACHE_WRITE_TOKENS: 'gen_ai.usage.cache_write_tokens',
     COST: 'gen_ai.cost',
 };
 export const ToolAttr = {
@@ -33,4 +37,20 @@ export const NoeticAttr = {
     SESSION_ID: 'noetic.session.id',
     /** Resource the session is scoped to (the run's `ctx.resourceId`), when set. */
     RESOURCE_ID: 'noetic.resource.id',
+    /** Id of the anchoring epoch the assembled view belongs to. */
+    CONTEXT_EPOCH_ID: 'noetic.context.epoch.id',
+    /** Assemblies served by the current epoch, including this one. */
+    CONTEXT_EPOCH_AGE: 'noetic.context.epoch.age',
+    /** Why the epoch re-anchored on this assembly, when it did. */
+    CONTEXT_REANCHOR_REASON: 'noetic.context.reanchor_reason',
+    /** Tokens in the anchor band (the cache-stable prefix). */
+    CONTEXT_ANCHOR_TOKENS: 'noetic.context.anchor_tokens',
+    /** Tokens in the live band (rendered after history). */
+    CONTEXT_LIVE_TOKENS: 'noetic.context.live_tokens',
+    /** Tokens spent superseding stale anchors. */
+    CONTEXT_DELTA_TOKENS: 'noetic.context.delta_tokens',
+    /** JSON array of `{ id, placement, served }` per contributing layer. */
+    CONTEXT_LAYER_PLACEMENTS: 'noetic.context.layer_placements',
+    /** JSON array of `{ id, rate, rebillTokens }` per contributing layer. */
+    CONTEXT_LAYER_CHURN: 'noetic.context.layer_churn',
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/core",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "type": "module",
   "description": "Step primitives, interpreter, runtime, and context layer contract for Noetic agents.",
   "license": "Apache-2.0",
@@ -66,8 +66,8 @@
     }
   },
   "dependencies": {
-    "@noetic-tools/context": "^1.1.0",
-    "@noetic-tools/types": "^3.0.0",
+    "@noetic-tools/context": "^1.2.0",
+    "@noetic-tools/types": "^3.1.0",
     "@openrouter/agent": "^0.6.0",
     "zod": "^4.0.0"
   },