@noetic-tools/types 2.3.0 → 3.1.0

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export * from './schemas/workflow.js';
 export * from './types/channel.js';
 export * from './types/common.js';
 export * from './types/context.js';
+export * from './types/context-cache.js';
 export * from './types/context-layer.js';
 export * from './types/context-parts/item-log.js';
 export * from './types/context-parts/layer-usage.js';
@@ -29,5 +30,6 @@ export * from './types/sub-harness.js';
 export * from './types/subprocess-adapter.js';
 export * from './types/tool.js';
 export * from './types/tool-context.js';
+export * from './util/content-hash.js';
 export * from './util/framework-cast.js';
 export * from './util/message-helpers.js';

package/dist/index.js

@@ -10,6 +10,7 @@ export * from './schemas/workflow.js';
 export * from './types/channel.js';
 export * from './types/common.js';
 export * from './types/context.js';
+export * from './types/context-cache.js';
 export * from './types/context-layer.js';
 export * from './types/context-parts/item-log.js';
 export * from './types/context-parts/layer-usage.js';
@@ -29,5 +30,6 @@ export * from './types/sub-harness.js';
 export * from './types/subprocess-adapter.js';
 export * from './types/tool.js';
 export * from './types/tool-context.js';
+export * from './util/content-hash.js';
 export * from './util/framework-cast.js';
 export * from './util/message-helpers.js';

package/dist/types/channel.d.ts

@@ -14,11 +14,13 @@ export interface Channel<T> {
     readonly capacity?: number;
 }
 /**
- * A channel that is writable from outside the execution tree (e.g. user input).
+ * A channel reachable from outside the execution tree: writable via
+ * `getChannelHandle` (e.g. user input) and readable via `getChannelStream`
+ * (e.g. approval requests posted to a chat platform).
  * @public
  */
 export interface ExternalChannel<T> extends Channel<T> {
-    /** Marker indicating the channel accepts writes from external callers. */
+    /** Marker indicating the channel accepts external readers and writers. */
     readonly external: true;
 }
 /** @public Handle for sending messages to a channel and checking its closed state. */

package/dist/types/common.d.ts

@@ -56,25 +56,41 @@ export interface TokenUsage {
     total: number;
     cached?: number;
 }
+/**
+ * @public Token counts for a single model round.
+ *
+ * `cachedTokens` and `cacheWriteTokens` are `undefined` — not `0` — when the
+ * provider reports no prompt-cache figures at all. Callers that steer on cache
+ * behaviour must tell "nothing was cached" apart from "this provider doesn't
+ * say", so the distinction is preserved rather than defaulted away.
+ */
+export interface RoundUsage {
+    inputTokens: number;
+    outputTokens: number;
+    /** Prompt tokens served from the provider's cache (a cache *read*). */
+    cachedTokens?: number;
+    /** Prompt tokens written into the provider's cache (a cache *write*). */
+    cacheWriteTokens?: number;
+}
 /** @public Metadata captured from the most recent step execution. */
 export interface StepMeta {
     toolCalls?: FunctionCallItem[];
-    usage?: {
-        inputTokens: number;
-        outputTokens: number;
-        cachedTokens?: number;
-    };
+    usage?: RoundUsage;
     cost?: number;
     responseItems?: ReadonlyArray<Item>;
 }
 /** @public Structured response returned by a model adapter after an LLM call. */
 export interface LLMResponse {
     items: Item[];
-    usage: {
-        inputTokens: number;
-        outputTokens: number;
-        cachedTokens?: number;
-    };
+    /** Totals across every round of the call. */
+    usage: RoundUsage;
+    /**
+     * Per-round breakdown, oldest first. Rounds after the first replay the same
+     * assembled view plus appended tool traffic, so they hit the prompt cache
+     * regardless of whether the first round did — only `rounds[0]` answers
+     * "was my prefix cached?".
+     */
+    rounds?: ReadonlyArray<RoundUsage>;
     cost?: number;
 }
 /** @public Configuration for the LLM provider used by the agent harness. */

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

@@ -0,0 +1,84 @@
+import type { Item } from './items.js';
+/**
+ * @public Tuning for the prompt-cache anchoring described on {@link LayerPlacement}.
+ *
+ * The defaults are chosen so that a layer set with no explicit placements still
+ * gets a stable prefix without any configuration.
+ */
+export interface ContextCacheConfig {
+    /** Master switch. Default `true`. When off, every layer renders before history, as it did before bands existed. */
+    enabled?: boolean;
+    /** Re-anchor when the first round reports fewer cached tokens than this. Default 100. */
+    minCachedTokens?: number;
+    /**
+     * Assemblies an epoch must reach before its cache figures are judged. Default 2.
+     * The first assembly after a re-anchor writes the cache rather than reading it,
+     * so judging it immediately would re-anchor forever and never pin anything.
+     */
+    minEpochAssemblies?: number;
+    /** Assemblies after which an epoch re-anchors regardless of cache figures. Default 50. */
+    maxEpochAssemblies?: number;
+    /** Re-anchor once supersedes cost more than this fraction of the anchor band. Default 0.15. */
+    deltaBudgetFraction?: number;
+    /** An `'auto'` layer changing at least this often moves to the live band. Default 0.5. */
+    autoDemoteChurn?: number;
+    /** An `'auto'` layer changing at most this often moves back to the anchor band. Default 0.2. */
+    autoPromoteChurn?: number;
+    /** Assemblies a layer must be watched for before its placement moves. Default 3. */
+    minChurnSamples?: number;
+    /** Fraction of the churn counters carried across a re-anchor. Default 0.5. */
+    churnDecay?: number;
+}
+/** @public Why an epoch re-anchored. */
+export type ReanchorReason = 'cold-start' | 'instructions-changed' | 'cache-miss' | 'delta-pressure' | 'delta-overflow' | 'max-age';
+/** @public One layer's rendered output, held byte-stable for the life of an epoch. */
+export interface AnchorPin {
+    layerId: string;
+    /** The exact items served every assembly this epoch. */
+    items: Item[];
+    tokenCount: number;
+    contentHash: string;
+    /** The layer state as of pinning. Held by reference — see `RenderDeltaParams.prevState`. */
+    state: unknown;
+    slot: number;
+}
+/** @public How often a layer's rendered output changes, and what that costs. */
+export interface LayerChurn {
+    /** Assemblies in which the layer produced output. */
+    observed: number;
+    /** Assemblies in which its output differed from its pin. */
+    changed: number;
+    /** Tokens invalidated downstream by those changes, had they not been pinned. */
+    rebillTokens: number;
+}
+/** @public One run of assemblies sharing a cacheable prompt prefix. */
+export interface ContextEpoch {
+    id: string;
+    /** Pinned output, keyed as `${scopeKey}:${layerId}`. */
+    pins: Map<string, AnchorPin>;
+    /** Band chosen for each `'auto'` layer at the last boundary, same key as `pins`. */
+    autoBand: Map<string, 'anchor' | 'live'>;
+    /** Hash of the resolved instructions this epoch was anchored against. */
+    instructionsHash: string;
+    assemblies: number;
+    anchorTokens: number;
+    deltaTokens: number;
+    /**
+     * Set once the provider has shown it reports no cache figures, or has missed
+     * so persistently that steering on its numbers is pointless. Suppresses the
+     * cache-miss trigger; age and delta pressure still apply.
+     */
+    cacheBlind: boolean;
+    /** Consecutive judged assemblies that came back a miss. */
+    misses: number;
+    lastReanchorReason: ReanchorReason;
+}
+/** @public Per-harness home for anchoring state, one epoch per cache lineage. */
+export interface ContextCacheStore {
+    /** Keyed by cache lineage — a thread at top level, an execution below it. */
+    epochs: Map<string, ContextEpoch>;
+    /** Churn per layer, outliving epochs so placement is not relearnt each time. */
+    churn: Map<string, LayerChurn>;
+    /** Re-anchors decided from a response, applied at the next assembly. */
+    pendingReanchor: Map<string, ReanchorReason>;
+}

package/dist/types/context-cache.js

@@ -0,0 +1,2 @@
+export {};
+//#endregion

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

@@ -179,6 +179,42 @@ export interface StoreParams<TState> {
 export interface StoreResult<TState> {
     state: TState;
 }
+/**
+ * @public Which band of the assembled view a layer's recall output sits in.
+ *
+ * Prompt caches match on a prefix, so a layer that re-renders every turn
+ * invalidates everything after it. The bands let stable content sit ahead of
+ * conversation history where it can be cached, and volatile content sit after
+ * it where re-rendering is nearly free.
+ *
+ * - `'anchor'` — before history. Pinned for the epoch: the bytes sent on the
+ *   first assembly are re-sent unchanged until the next re-anchor, and any
+ *   change is published as a supersede instead of rewriting the prefix.
+ * - `'live'` — after history. Re-rendered freely. Use for content that changes
+ *   every turn, or whose `recall()` mutates state and so cannot be replayed.
+ * - `'auto'` (default) — starts anchored; the runtime may move it to `'live'`
+ *   at an epoch boundary once it has watched how often the layer changes.
+ *   An explicit `'anchor'` or `'live'` is never overridden.
+ */
+export type LayerPlacement = 'anchor' | 'live' | 'auto';
+/** @public Parameters passed to a context layer's `renderDelta` hook when its pinned output goes stale. */
+export interface RenderDeltaParams<TState = unknown> {
+    /** The items still pinned in the anchor band — what the model can currently see. */
+    prev: ReadonlyArray<Item>;
+    /** The freshly recalled items that would have replaced them. */
+    next: ReadonlyArray<Item>;
+    /**
+     * The layer state captured when `prev` was pinned. Best-effort: it is held by
+     * reference, so a layer that mutates its state in place sees the current
+     * object here rather than a snapshot.
+     */
+    prevState: TState | undefined;
+    /** The layer's current state. */
+    state: TState | undefined;
+    ctx: ExecutionContext;
+    /** Soft token budget for the returned text. */
+    budget: number;
+}
 /** @public Parameters passed to a context layer's `onSpawn` hook when a child execution starts. */
 export interface SpawnParams<TState> {
     parentState: TState;
@@ -297,6 +333,16 @@ export interface ContextLayerHooks<TState = unknown> {
      * Use for: capping history, summarising old turns, redacting items.
      */
     projectHistory?(params: ProjectHistoryParams<TState>): Promise<ProjectHistoryResult>;
+    /**
+     * Called for an anchored layer whose pinned output has gone stale, to describe
+     * the change compactly instead of re-sending the whole block.
+     *
+     * Return `null` to fall back to the default, which republishes the full new
+     * content. Worth implementing only when the layer's output is large and its
+     * changes are small — a file set where one file changed, a ledger that gained
+     * a row. Never called for layers in the `'live'` band, which re-render anyway.
+     */
+    renderDelta?(params: RenderDeltaParams<TState>): Promise<string | null>;
 }
 /**
  * A composable context layer that participates in the recall/store lifecycle.
@@ -343,6 +389,11 @@ export interface ContextLayer<TState = unknown> {
     itemSchemas?: Pick<ItemSchemaExtensions, 'developerMessages' | 'items'>;
     /** Default re-render timing when `onItemAppend` requests a re-render. */
     rerenderTiming?: 'immediate' | 'batched';
+    /**
+     * Which band of the assembled view this layer's recall output sits in, and so
+     * whether it is pinned for the prompt cache. Defaults to `'auto'`.
+     */
+    placement?: LayerPlacement;
 }
 /** @public Configuration for how the runtime projects conversation items into the model's context window. */
 export interface ProjectionPolicy {

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

@@ -1,3 +1,4 @@
+import type { ReanchorReason } from '../context-cache.js';
 import type { Item } from '../items.js';
 /** @public Per-layer contribution to the context window on the most recent LLM call. */
 export interface LayerUsageEntry {
@@ -5,6 +6,27 @@ export interface LayerUsageEntry {
     readonly tokenCount: number;
     /** Items this layer contributed to the context view for the last LLM call. */
     readonly items: ReadonlyArray<Item>;
+    /** Which band the layer rendered into. */
+    readonly placement: 'anchor' | 'live';
+    /** `'pinned'` when the items are a replay of an earlier render, held for the prompt cache. */
+    readonly served: 'fresh' | 'pinned';
+    /** Whether the layer's fresh output differed from its pin, and so was superseded. */
+    readonly changed: boolean;
+    /** Share of watched assemblies in which this layer's output changed, 0–1. */
+    readonly churnRate: number;
+    /** Tokens this layer's changes would have re-billed had it not been pinned. */
+    readonly rebillTokens: number;
+}
+/** @public Prompt-cache anchoring state behind the most recent assembly. */
+export interface EpochUsage {
+    readonly id: string;
+    /** Assemblies served by this epoch, including the one just made. */
+    readonly age: number;
+    readonly anchorTokens: number;
+    readonly liveTokens: number;
+    readonly deltaTokens: number;
+    /** Set only on an assembly that re-anchored. */
+    readonly reanchorReason?: ReanchorReason;
 }
 /** @public Breakdown of the context window as of the most recent LLM call in an execution. */
 export interface LastLayerUsage {
@@ -15,4 +37,6 @@ export interface LastLayerUsage {
     readonly toolsTokens: number;
     readonly historyTokens: number;
     readonly totalUsedTokens: number;
+    /** Absent when context caching is switched off. */
+    readonly epoch?: EpochUsage;
 }

package/dist/types/context.d.ts

@@ -2,6 +2,7 @@ import type { ZodType } from 'zod';
 import type { ItemSchemaRegistry } from '../schemas/item.js';
 import type { Channel, ChannelHandle, ExternalChannel } from './channel.js';
 import type { LLMResponse, ModelParams, StepMeta, TokenUsage } from './common.js';
+import type { ContextCacheConfig, ContextCacheStore } from './context-cache.js';
 import type { ContextData, ContextLayer, ProjectionPolicy, StorageAdapter } from './context-layer.js';
 import type { ItemLog } from './context-parts/item-log.js';
 import type { LastLayerUsage } from './context-parts/layer-usage.js';
@@ -128,6 +129,8 @@ export interface ContextHarness {
         readonly params: Record<string, unknown>;
         /** Harness-wide default projection policy; a step's `projection` overrides it. */
         readonly projection?: ProjectionPolicy;
+        /** Tuning for prompt-cache anchoring. */
+        readonly contextCache?: ContextCacheConfig;
     };
     readonly fs: FsAdapter;
     readonly shell: ShellAdapter;
@@ -159,6 +162,8 @@ export interface ContextHarness {
     beforeToolCall(layers: ContextLayer[], toolName: string, toolArgs: unknown, ctx: Context): Promise<SteeringDecision>;
     afterModelCall(layers: ContextLayer[], response: LLMResponse, ctx: Context): Promise<SteeringDecision>;
     runAppendPipeline(layers: ContextLayer[], items: import('./items.js').Item[], ctx: Context): Promise<ContextAppendPipelineResult>;
+    /** Pinned anchor output and epoch bookkeeping for prompt-cache anchoring. Absent on a harness that predates it. */
+    readonly contextCache?: ContextCacheStore;
     recallLayers(layers: ContextLayer[], input: string, ctx: Context): Promise<ContextRecallLayerOutput[]>;
     recallLayersAtomic(layers: ContextLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<ContextRecallLayerOutput[]>;
     recallLayersEventual(layers: ContextLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<ContextRecallLayerOutput[]>;
@@ -177,6 +182,8 @@ export interface ContextHarness {
     }): Promise<T>;
     tryRecv<T>(channel: Channel<T>, ctx: Context): T | null;
     getChannelHandle<T>(channel: ExternalChannel<T>, executionId: string): ChannelHandle<T>;
+    /** Read-side counterpart to `getChannelHandle` — see `AgentHarnessContract.getChannelStream`. */
+    getChannelStream<T>(channel: ExternalChannel<T>, executionId: string): AsyncIterable<T>;
     initLayers(layers: ContextLayer[], ctx: Context, storage: StorageAdapter): Promise<void>;
     disposeLayers(layers: ContextLayer[], ctx: Context): Promise<void>;
     checkpoint(ctx: Context): Promise<void>;

package/dist/types/runtime.d.ts

@@ -2,6 +2,7 @@ import type { ZodType } from 'zod';
 import type { Channel, ChannelHandle, ExternalChannel } from './channel.js';
 import type { LLMResponse, ModelParams, ServerToolSpec } from './common.js';
 import type { Context, CwdState, RestoreContextOptions } from './context.js';
+import type { ContextCacheConfig, ContextCacheStore } from './context-cache.js';
 import type { ContextData, ContextLayer, ProjectionPolicy, StorageAdapter } from './context-layer.js';
 import type { DetachedHandle } from './detached.js';
 import type { FsAdapter } from './fs-adapter.js';
@@ -32,6 +33,8 @@ export interface AgentConfig<TParams extends Record<string, unknown> = Record<st
     projection?: ProjectionPolicy;
     /** When true, every layer is recalled atomically regardless of its `recallMode` (no eventual/cached recall). */
     forceAtomicRecall?: boolean;
+    /** Tuning for prompt-cache anchoring. See `ContextCacheConfig` for the defaults. */
+    contextCache?: ContextCacheConfig;
 }
 /** @public How a message submitted during an active turn is delivered to the model.
  *
@@ -234,6 +237,24 @@ export interface AgentHarnessContract<TParams extends Record<string, unknown> =
     }): Promise<T>;
     tryRecv<T>(channel: Channel<T>, ctx: Context): T | null;
     getChannelHandle<T>(channel: ExternalChannel<T>, executionId: string): ChannelHandle<T>;
+    /**
+     * Read-side counterpart to `getChannelHandle`: subscribe to values the agent
+     * sends on an external channel. Delivery is CHANNEL-scoped (state is keyed
+     * by channel name per harness) — `executionId` bounds only the
+     * subscription's lifetime: the iterable ends when that root execution
+     * completes (success, failure, or cancellation), draining buffered values
+     * first. An id no execution runs under never closes, giving a
+     * harness-lifetime stream ended via `iterator.return()`. The returned
+     * iterable owns a single iterator; subscribe again for a second consumer.
+     */
+    getChannelStream<T>(channel: ExternalChannel<T>, executionId: string): AsyncIterable<T>;
+    /**
+     * Pinned anchor output and epoch bookkeeping for prompt-cache anchoring,
+     * shared by every thread on this harness. Optional so a hand-written harness
+     * stays valid: without it nothing is pinned across turns and layers render
+     * fresh every time, as they did before anchoring existed.
+     */
+    readonly contextCache?: ContextCacheStore;
     initLayers(layers: ContextLayer[], ctx: Context, storage: StorageAdapter): Promise<void>;
     recallLayers(layers: ContextLayer[], input: string, ctx: Context): Promise<RecallLayerOutput[]>;
     /** Recall only atomic layers (or all layers when the harness forces atomic recall). Blocks until complete. */
@@ -296,6 +317,13 @@ export interface RecallLayerOutput {
     layerId: string;
     items: Item[];
     tokenCount: number;
+    /**
+     * Set when the layer's `recall` returned new state, meaning the call changed
+     * something and cannot be replayed. Such a layer is never pinned — serving an
+     * older render would drop the very thing the call committed (the steering
+     * layer, for one, drains its queue as it renders).
+     */
+    mutatedState?: boolean;
 }
 /** @public A request to re-render the context window, collected from onItemAppend hooks. */
 export interface RerenderRequest {

package/dist/util/content-hash.d.ts

@@ -0,0 +1,25 @@
+import type { Item } from '../types/items.js';
+/**
+ * @public Hash a string to 16 hex chars (64 bits).
+ *
+ * Not cryptographic — it exists to answer "is this byte-identical to last
+ * time?" cheaply. 64 bits keeps accidental collisions far enough away that a
+ * stale-content false match is not a practical concern.
+ *
+ * Adapted from bryc's cyrb64 (public domain):
+ * https://github.com/bryc/code/blob/master/jshash/experimental/cyrb1.js
+ */
+export declare function hashString(input: string): string;
+/**
+ * @public Hash rendered items by the content that actually reaches the model.
+ *
+ * `createMessage` mints a fresh `id` on every render, so hashing items verbatim
+ * would report a change every turn even when the text is identical. Message
+ * items are sent as `{role, content}` alone, so `id` and `status` are dropped
+ * before hashing; every other item type is hashed whole, since their ids can
+ * reach the wire.
+ *
+ * Object keys are sorted, so a layer that builds its items in a different key
+ * order between renders still hashes the same.
+ */
+export declare function hashItems(items: ReadonlyArray<Item>): string;

package/dist/util/content-hash.js

@@ -0,0 +1,65 @@
+//#region Public API
+/**
+ * @public Hash a string to 16 hex chars (64 bits).
+ *
+ * Not cryptographic — it exists to answer "is this byte-identical to last
+ * time?" cheaply. 64 bits keeps accidental collisions far enough away that a
+ * stale-content false match is not a practical concern.
+ *
+ * Adapted from bryc's cyrb64 (public domain):
+ * https://github.com/bryc/code/blob/master/jshash/experimental/cyrb1.js
+ */
+export function hashString(input) {
+    let h1 = 0xdeadbeef;
+    let h2 = 0x41c6ce57;
+    for (let i = 0; i < input.length; i++) {
+        const ch = input.charCodeAt(i);
+        h1 = Math.imul(h1 ^ ch, 2654435761);
+        h2 = Math.imul(h2 ^ ch, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507);
+    h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507);
+    h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    return `${(h2 >>> 0).toString(16).padStart(8, '0')}${(h1 >>> 0).toString(16).padStart(8, '0')}`;
+}
+/**
+ * @public Hash rendered items by the content that actually reaches the model.
+ *
+ * `createMessage` mints a fresh `id` on every render, so hashing items verbatim
+ * would report a change every turn even when the text is identical. Message
+ * items are sent as `{role, content}` alone, so `id` and `status` are dropped
+ * before hashing; every other item type is hashed whole, since their ids can
+ * reach the wire.
+ *
+ * Object keys are sorted, so a layer that builds its items in a different key
+ * order between renders still hashes the same.
+ */
+export function hashItems(items) {
+    return hashString(stableStringify(items.map(wireShape)));
+}
+//#endregion
+//#region Helpers
+/** Drops the fields the provider adapter strips before sending a message item. */
+function wireShape(item) {
+    if (item.type !== 'message') {
+        return item;
+    }
+    const { id: _id, status: _status, ...rest } = item;
+    return rest;
+}
+/** `JSON.stringify` with object keys sorted at every depth. */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value) ?? 'null';
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(',')}]`;
+    }
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
+    return `{${entries.join(',')}}`;
+}
+//#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/types",
-  "version": "2.3.0",
+  "version": "3.1.0",
   "type": "module",
   "description": "Foundational type contracts and primitives shared across the Noetic framework (items, LLM config, adapters, steering, errors).",
   "license": "Apache-2.0",