@noetic-tools/context 1.6.0 → 1.7.0

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

@@ -27,6 +27,13 @@ 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;
+/**
+ * Drop the pins of layers that left a lineage's layer set — a closing
+ * `withContext` boundary. A pin outlives its layer by design (dropping it
+ * shortens the cached prefix), so a scoped layer must be unpinned explicitly or
+ * its last render keeps replaying after its scope ends.
+ */
+export declare function unpinLayers(store: ContextCacheStore, key: string, layers: ContextLayer[]): 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. */

package/dist/context/cache-anchoring.js

@@ -66,6 +66,22 @@ export function dropLineage(store, key) {
     store.epochs.delete(key);
     store.pendingReanchor.delete(key);
 }
+/**
+ * Drop the pins of layers that left a lineage's layer set — a closing
+ * `withContext` boundary. A pin outlives its layer by design (dropping it
+ * shortens the cached prefix), so a scoped layer must be unpinned explicitly or
+ * its last render keeps replaying after its scope ends.
+ */
+export function unpinLayers(store, key, layers) {
+    const epoch = store.epochs.get(key);
+    if (!epoch) {
+        return;
+    }
+    for (const layer of layers) {
+        epoch.pins.delete(pinKey(layer));
+        epoch.autoBand.delete(pinKey(layer));
+    }
+}
 /** Read a layer's churn record, creating an empty one on first sight. */
 export function churnFor(store, key) {
     const found = store.churn.get(key);

package/dist/context/hook-call.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Timed, traced calls into context layer hooks. Each call of a traced hook adds
+ * one `layer.hook` event to the span of the context it runs in (`ctx.trace`),
+ * shaped as a `LayerTraceSpan`. Events rather than child spans: an
+ * `ExecutionContext` can annotate its span but not open one.
+ */
+import type { ExecutionContext, LayerTraceSpan } from '@noetic-tools/types';
+type TracedHook = LayerTraceSpan['hook'];
+interface HookCall<T> {
+    ctx: ExecutionContext;
+    layerId: string;
+    hook: TracedHook;
+    /** Milliseconds before the call fails as a timeout; `0` or less waits forever. */
+    timeout: number;
+    run: () => Promise<T>;
+    /** Reads a recall's budget and item count from the hook's result. */
+    measure?: (result: T) => Pick<LayerTraceSpan, 'budget' | 'itemCount'>;
+}
+/** Span event recording one layer hook call. Attributes follow `LayerTraceSpan`. */
+export declare const LAYER_HOOK_EVENT = "layer.hook";
+/**
+ * Runs a layer hook under its timeout and records a `layer.hook` event for it.
+ * Rethrows whatever the hook threw (or the timeout), so callers keep their own
+ * failure handling.
+ */
+export declare function callHook<T>({ ctx, layerId, hook, timeout, run, measure, }: HookCall<T>): Promise<T>;
+/** Records a hook the layer defines but the lifecycle did not call. */
+export declare function traceSkipped(ctx: ExecutionContext, layerId: string, hook: TracedHook): void;
+/** Runs a hook under a timeout without tracing it, for hooks outside `LayerTraceSpan`. */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T>;
+export {};

package/dist/context/hook-call.js

@@ -0,0 +1,92 @@
+/**
+ * Timed, traced calls into context layer hooks. Each call of a traced hook adds
+ * one `layer.hook` event to the span of the context it runs in (`ctx.trace`),
+ * shaped as a `LayerTraceSpan`. Events rather than child spans: an
+ * `ExecutionContext` can annotate its span but not open one.
+ */
+//#endregion
+//#region Public API
+/** Span event recording one layer hook call. Attributes follow `LayerTraceSpan`. */
+export const LAYER_HOOK_EVENT = 'layer.hook';
+/**
+ * Runs a layer hook under its timeout and records a `layer.hook` event for it.
+ * Rethrows whatever the hook threw (or the timeout), so callers keep their own
+ * failure handling.
+ */
+export async function callHook({ ctx, layerId, hook, timeout, run, measure, }) {
+    const started = performance.now();
+    try {
+        const result = await withTimeout(run(), timeout);
+        traceHook(ctx, {
+            layerId,
+            hook,
+            duration: performance.now() - started,
+            status: 'ok',
+            ...measure?.(result),
+        });
+        return result;
+    }
+    catch (e) {
+        traceHook(ctx, {
+            layerId,
+            hook,
+            duration: performance.now() - started,
+            status: e instanceof HookTimeout ? 'timeout' : 'error',
+            error: {
+                message: e instanceof Error ? e.message : String(e),
+            },
+        });
+        throw e;
+    }
+}
+/** Records a hook the layer defines but the lifecycle did not call. */
+export function traceSkipped(ctx, layerId, hook) {
+    traceHook(ctx, {
+        layerId,
+        hook,
+        duration: 0,
+        status: 'skipped',
+    });
+}
+/** Runs a hook under a timeout without tracing it, for hooks outside `LayerTraceSpan`. */
+export async function withTimeout(promise, ms) {
+    if (ms <= 0) {
+        return promise;
+    }
+    let timer;
+    return Promise.race([
+        promise.finally(() => clearTimeout(timer)),
+        new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new HookTimeout(ms)), ms);
+        }),
+    ]);
+}
+//#endregion
+//#region Helpers
+class HookTimeout extends Error {
+    constructor(ms) {
+        super(`Timeout after ${ms}ms`);
+    }
+}
+/** Span event attributes hold only scalars, so nested fields flatten to dotted keys. */
+function traceHook(ctx, span) {
+    const attributes = {
+        layerId: span.layerId,
+        hook: span.hook,
+        duration: span.duration,
+        status: span.status,
+    };
+    if (span.itemCount !== undefined) {
+        attributes.itemCount = span.itemCount;
+    }
+    if (span.budget) {
+        attributes['budget.allocated'] = span.budget.allocated;
+        attributes['budget.used'] = span.budget.used;
+        attributes['budget.yielded'] = span.budget.yielded;
+    }
+    if (span.error) {
+        attributes['error.message'] = span.error.message;
+    }
+    ctx.trace.addEvent(LAYER_HOOK_EVENT, attributes);
+}
+//#endregion

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

@@ -13,6 +13,13 @@ export interface LayerStateStore {
      */
     has?(executionId: string, layerId: string): boolean;
     cleanup(executionId: string): void;
+    /**
+     * Forget one layer's state, durable target, and disabled mark for an
+     * execution, leaving the execution's other layers alone. Optional so custom
+     * stores keep compiling; without it, a scoped dispose leaves the state in
+     * place for the next `init` to overwrite.
+     */
+    drop?(executionId: string, layerId: string): void;
     diagnostic: (layerId: string, hook: string, error: unknown) => void;
     /**
      * Register a durable write-through target for a layer's state under an
@@ -28,7 +35,8 @@ export interface LayerStateStore {
     flush?(executionId: string): Promise<void>;
     /**
      * Mark a layer disabled for an execution (its `init` failed with
-     * `onInitError: 'disable'`). Disabled layers are skipped by every later
+     * `onInitError: 'disable'`, or its `onSpawn` returned `null` or failed for
+     * a child execution). Disabled layers are skipped by every later
      * hook. Optional so custom stores keep compiling; without explicit
      * tracking, the lifecycle falls back to the legacy sentinel (init-bearing
      * layer with no state).
@@ -113,6 +121,12 @@ interface DisposeLayersParams {
     layers: ContextLayer[];
     ctx: ExecutionContext;
     store: LayerStateStore;
+    /**
+     * The layers share their execution with layers that stay live (a
+     * `withContext` boundary closing). Drop only these layers' state instead of
+     * cleaning up the whole execution.
+     */
+    scoped?: boolean;
 }
 interface BeforeToolCallLayersParams {
     layers: ContextLayer[];
@@ -231,7 +245,7 @@ interface NotifyDecisionParams {
  * what an earlier one recorded.
  */
 export declare function notifyDecision({ layers, record, ctx, store, recallCache, }: NotifyDecisionParams): Promise<void>;
-export declare function disposeLayers({ layers, ctx, store }: DisposeLayersParams): Promise<void>;
+export declare function disposeLayers({ layers, ctx, store, scoped, }: DisposeLayersParams): Promise<void>;
 export declare function spawnLayers({ layers, parentCtx, childCtx, store, itemSchemas, storage, }: SpawnLayersParams): Promise<{
     layerId: string;
     childState: unknown;

package/dist/context/layer-lifecycle.js

@@ -1,4 +1,5 @@
 import { createMessage, defaultItemSchemaRegistry, estimateTokens, frameworkCast, NoeticConfigError, NoeticErrorImpl, SteeringAction, } from '@noetic-tools/types';
+import { callHook, traceSkipped, withTimeout } from './hook-call.js';
 import { createScopedStorage, resolveScopeKey } from './scope.js';
 /** Maximum allowed re-render depth to prevent infinite loops */
 const MAX_RERENDER_DEPTH = 3;
@@ -91,6 +92,11 @@ export function createLayerStateStore(diagnostic) {
             durables.delete(executionId);
             disabled.delete(executionId);
         },
+        drop(executionId, layerId) {
+            states.get(executionId)?.delete(layerId);
+            durables.get(executionId)?.delete(layerId);
+            disabled.get(executionId)?.delete(layerId);
+        },
         diagnostic: report,
     };
 }
@@ -136,18 +142,6 @@ function recallCacheKey(layer, ctx) {
     return `${resolveScopeKey(layer.scope, ctx)}:${layer.id}`;
 }
 //#endregion
-async function withTimeout(promise, ms) {
-    if (ms <= 0) {
-        return promise;
-    }
-    let timer;
-    return Promise.race([
-        promise.finally(() => clearTimeout(timer)),
-        new Promise((_, reject) => {
-            timer = setTimeout(() => reject(new Error(`Timeout after ${ms}ms`)), ms);
-        }),
-    ]);
-}
 export function mostRestrictive(decisions) {
     const guidances = [];
     let hasGuide = false;
@@ -202,18 +196,25 @@ export async function initLayers({ layers, ctx, storage, store, keep = false, })
         if (!layer.hooks.init) {
             continue;
         }
+        const init = layer.hooks.init;
         if (keep && store.has?.(ctx.executionId, layer.id)) {
+            traceSkipped(ctx, layer.id, 'init');
             continue;
         }
         const scopeKey = resolveScopeKey(layer.scope, ctx);
         const scopedStorage = createScopedStorage(storage, layer.id, scopeKey);
         try {
-            const timeout = layer.timeouts?.init ?? 1e4;
-            const result = await withTimeout(layer.hooks.init({
-                storage: scopedStorage,
-                scopeKey,
+            const result = await callHook({
                 ctx,
-            }), timeout);
+                layerId: layer.id,
+                hook: 'init',
+                timeout: layer.timeouts?.init ?? 1e4,
+                run: () => init({
+                    storage: scopedStorage,
+                    scopeKey,
+                    ctx,
+                }),
+            });
             store.set(ctx.executionId, layer.id, result.state);
         }
         catch (e) {
@@ -272,6 +273,9 @@ export async function recallLayers({ layers, query, ctx, log, budgets, store, it
             layer,
             state: stored,
         })) {
+            if (!peek) {
+                traceSkipped(ctx, layer.id, 'recall');
+            }
             continue; // was disabled
         }
         // Skipping the write is not enough for a peek: a hook may mutate the
@@ -281,15 +285,27 @@ export async function recallLayers({ layers, query, ctx, log, budgets, store, it
             continue;
         }
         const budget = budgets.get(layer.id) ?? 0;
+        const recall = layer.hooks.recall;
+        const run = () => recall({
+            log,
+            query,
+            ctx,
+            state,
+            budget,
+        });
+        const timeout = layer.timeouts?.recall ?? 5e3;
         try {
-            const timeout = layer.timeouts?.recall ?? 5e3;
-            const result = await withTimeout(layer.hooks.recall({
-                log,
-                query,
-                ctx,
-                state,
-                budget,
-            }), timeout);
+            // A peek renders without leaving a trace, so it records no event either.
+            const result = peek
+                ? await withTimeout(run(), timeout)
+                : await callHook({
+                    ctx,
+                    layerId: layer.id,
+                    hook: 'recall',
+                    timeout,
+                    run,
+                    measure: (output) => measureRecall(output, budget),
+                });
             if (!result) {
                 continue;
             }
@@ -324,6 +340,24 @@ export async function recallLayers({ layers, query, ctx, log, budgets, store, it
     return results;
 }
 const PEEK_UNSAFE = Symbol('peek-unsafe');
+/** Budget and item count for a `layer.hook` recall event. */
+function measureRecall(output, allocated) {
+    const measured = (used, itemCount) => ({
+        budget: {
+            allocated,
+            used,
+            yielded: Math.max(0, allocated - used),
+        },
+        itemCount,
+    });
+    if (!output) {
+        return measured(0, 0);
+    }
+    if (typeof output === 'string') {
+        return measured(estimateTokens(output), 1);
+    }
+    return measured(output.tokenCount, output.items.length);
+}
 /** A deep copy, or `PEEK_UNSAFE` when the state cannot be copied (it holds functions). */
 function copyForPeek(state) {
     try {
@@ -415,6 +449,7 @@ export async function storeLayers({ layers, response, ctx, log, store, recallCac
             layer,
             state,
         })) {
+            traceSkipped(ctx, layer.id, 'store');
             continue;
         }
         snapshots.push({
@@ -424,15 +459,20 @@ export async function storeLayers({ layers, response, ctx, log, store, recallCac
         });
     }
     await Promise.allSettled(snapshots.map(async ({ layer, state, storeFn }) => {
-        const timeout = layer.timeouts?.store ?? 3e4;
         try {
-            const result = await withTimeout(storeFn({
-                newItems: response.items,
-                log,
-                response,
+            const result = await callHook({
                 ctx,
-                state,
-            }), timeout);
+                layerId: layer.id,
+                hook: 'store',
+                timeout: layer.timeouts?.store ?? 3e4,
+                run: () => storeFn({
+                    newItems: response.items,
+                    log,
+                    response,
+                    ctx,
+                    state,
+                }),
+            });
             // `'state' in result` (not `!== undefined`) so a layer can explicitly
             // clear its state by returning `{ state: undefined }`. The store's
             // durable write-through mirrors the write (clearing deletes the
@@ -493,7 +533,7 @@ export async function notifyDecision({ layers, record, ctx, store, recallCache,
     }
     await store.flush?.(ctx.executionId);
 }
-export async function disposeLayers({ layers, ctx, store }) {
+export async function disposeLayers({ layers, ctx, store, scoped = false, }) {
     // Sequential, REVERSE array order
     const reversed = [
         ...layers,
@@ -511,13 +551,20 @@ export async function disposeLayers({ layers, ctx, store }) {
             layer,
             state,
         })) {
+            traceSkipped(ctx, layer.id, 'dispose');
             continue;
         }
+        const dispose = layer.hooks.dispose;
         try {
-            const timeout = layer.timeouts?.dispose ?? 5e3;
-            await withTimeout(layer.hooks.dispose({
-                state,
-            }), timeout);
+            await callHook({
+                ctx,
+                layerId: layer.id,
+                hook: 'dispose',
+                timeout: layer.timeouts?.dispose ?? 5e3,
+                run: () => dispose({
+                    state,
+                }),
+            });
         }
         catch (e) {
             store.diagnostic(layer.id, 'dispose', e);
@@ -525,7 +572,13 @@ export async function disposeLayers({ layers, ctx, store }) {
     }
     // Settle any in-flight durable mirror writes before dropping registrations.
     await store.flush?.(ctx.executionId);
-    store.cleanup(ctx.executionId);
+    if (!scoped) {
+        store.cleanup(ctx.executionId);
+        return;
+    }
+    for (const layer of layers) {
+        store.drop?.(ctx.executionId, layer.id);
+    }
 }
 export async function spawnLayers({ layers, parentCtx, childCtx, store, itemSchemas = defaultItemSchemaRegistry, storage, }) {
     if (storage) {
@@ -554,25 +607,40 @@ export async function spawnLayers({ layers, parentCtx, childCtx, store, itemSche
             layer,
             state: parentState,
         })) {
+            traceSkipped(parentCtx, layer.id, 'onSpawn');
             continue;
         }
+        const onSpawn = layer.hooks.onSpawn;
         try {
-            const timeout = layer.timeouts?.onSpawn ?? 1e4;
-            const result = await withTimeout(layer.hooks.onSpawn({
-                parentState,
-                childCtx,
-            }), timeout);
-            if (result && result.childState !== null) {
+            const result = await callHook({
+                ctx: parentCtx,
+                layerId: layer.id,
+                hook: 'onSpawn',
+                timeout: layer.timeouts?.onSpawn ?? 1e4,
+                run: () => onSpawn({
+                    parentState,
+                    childCtx,
+                }),
+            });
+            // A `null` result opts the layer out of this child: every later hook
+            // skips it for the child's execution.
+            if (!result) {
+                store.disable?.(childCtx.executionId, layer.id);
+                continue;
+            }
+            // `childState: null` still injects items; the child just gets no state.
+            if (result.childState !== null) {
                 store.set(childCtx.executionId, layer.id, result.childState);
-                results.push({
-                    layerId: layer.id,
-                    childState: result.childState,
-                    items: layerItemSchemas(layer, itemSchemas).parseMany(result.items ?? []),
-                });
             }
+            results.push({
+                layerId: layer.id,
+                childState: result.childState,
+                items: layerItemSchemas(layer, itemSchemas).parseMany(result.items ?? []),
+            });
         }
         catch (e) {
             store.diagnostic(layer.id, 'onSpawn', e);
+            store.disable?.(childCtx.executionId, layer.id);
         }
     }
     return results;
@@ -599,17 +667,24 @@ export async function returnLayers({ layers, stepId, parentCtx, childCtx, childL
         // initialized state can still be seeded from the child. Skip only when the
         // child produced nothing.
         if (childState === undefined) {
+            traceSkipped(childCtx, layer.id, 'onReturn');
             continue;
         }
+        const onReturn = layer.hooks.onReturn;
         try {
-            const timeout = layer.timeouts?.onReturn ?? 1e4;
-            const returnResult = await withTimeout(layer.hooks.onReturn({
-                childState,
-                childLog,
-                parentState,
-                result: currentResult,
-                childCtx,
-            }), timeout);
+            const returnResult = await callHook({
+                ctx: childCtx,
+                layerId: layer.id,
+                hook: 'onReturn',
+                timeout: layer.timeouts?.onReturn ?? 1e4,
+                run: () => onReturn({
+                    childState,
+                    childLog,
+                    parentState,
+                    result: currentResult,
+                    childCtx,
+                }),
+            });
             if (returnResult?.parentState !== undefined) {
                 store.set(parentCtx.executionId, layer.id, returnResult.parentState);
             }
@@ -648,16 +723,23 @@ export async function completeLayers({ layers, ctx, log, outcome, store, }) {
             layer,
             state,
         })) {
+            traceSkipped(ctx, layer.id, 'onComplete');
             continue;
         }
+        const onComplete = layer.hooks.onComplete;
         try {
-            const timeout = layer.timeouts?.onComplete ?? 3e4;
-            const result = await withTimeout(layer.hooks.onComplete({
-                log,
+            const result = await callHook({
                 ctx,
-                state,
-                outcome,
-            }), timeout);
+                layerId: layer.id,
+                hook: 'onComplete',
+                timeout: layer.timeouts?.onComplete ?? 3e4,
+                run: () => onComplete({
+                    log,
+                    ctx,
+                    state,
+                    outcome,
+                }),
+            });
             if (result && 'state' in result) {
                 store.set(ctx.executionId, layer.id, result.state);
             }

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export * from './context/budget.js';
 export * from './context/cache-anchoring.js';
 export * from './context/exec-context-factory.js';
 export * from './context/function-call-utils.js';
+export { LAYER_HOOK_EVENT } from './context/hook-call.js';
 export * from './context/layer-api.js';
 export * from './context/layer-lifecycle.js';
 export * from './context/layer-provides.js';

package/dist/index.js

@@ -11,6 +11,7 @@ export * from './context/budget.js';
 export * from './context/cache-anchoring.js';
 export * from './context/exec-context-factory.js';
 export * from './context/function-call-utils.js';
+export { LAYER_HOOK_EVENT } from './context/hook-call.js';
 export * from './context/layer-api.js';
 export * from './context/layer-lifecycle.js';
 export * from './context/layer-provides.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/context",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "type": "module",
   "description": "Context layer system for Noetic agents: the ContextLayer contract, lifecycle, budget/projection machinery, and built-in layer implementations.",
   "license": "Apache-2.0",
@@ -44,7 +44,7 @@
     "zod": "^4.0.0"
   },
   "dependencies": {
-    "@noetic-tools/types": "^3.7.0",
+    "@noetic-tools/types": "^3.8.0",
     "zod": "^4.0.0"
   },
   "scripts": {