@noetic-tools/context 1.6.0 → 1.8.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/exec-context-factory.js

@@ -1,4 +1,5 @@
 import { estimateTokens } from '@noetic-tools/types';
+import { exportSpans } from './span-export.js';
 /**
  * Maps a full `Context` to the lightweight `ExecutionContext` consumed by context layer hooks.
  * Centralised here so the mapping stays consistent across agent-harness, layer-api, and the
@@ -24,7 +25,22 @@ export function contextToExecCtx(ctx, overrides) {
         trace: {
             setAttribute: (key, value) => ctx.span.setAttribute(key, value),
             addEvent: (name, attributes) => ctx.span.addEvent(name, attributes),
+            createSpan: (name) => openSpan(ctx, name),
         },
         readLayerState: (layerId) => ctx.harness.getLayerState(readLayerStateId, layerId),
     };
 }
+/** Opens a span under `ctx.span` that exports itself to the harness when it ends. */
+function openSpan(ctx, name) {
+    const span = ctx.harness.createSpan(name, ctx.span);
+    return {
+        setAttribute: (key, value) => span.setAttribute(key, value),
+        addEvent: (event, attributes) => span.addEvent(event, attributes),
+        end: async () => {
+            span.end();
+            await exportSpans(ctx.harness.traceExporter, [
+                span,
+            ]);
+        },
+    };
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Timed, traced calls into context layer hooks. Each call of a traced hook is
+ * recorded as one `layer.hook` record shaped as a `LayerTraceSpan`: a child
+ * span of the context's span when the context can open one
+ * (`ctx.trace.createSpan`), otherwise an event on the context's span. Never
+ * both, so a backend sees each call once.
+ */
+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'>;
+}
+/** Name of the span (or span event) recording one layer hook call. */
+export declare const LAYER_HOOK_EVENT = "layer.hook";
+/** Attributes of a `layer.hook` span. A span times itself, so it carries no duration. */
+export declare const LayerHookAttr: {
+    readonly LAYER_ID: "noetic.layer.id";
+    readonly HOOK: "noetic.layer.hook";
+    readonly STATUS: "noetic.layer.status";
+    readonly ITEM_COUNT: "noetic.layer.item_count";
+    readonly BUDGET_ALLOCATED: "noetic.layer.budget.allocated";
+    readonly BUDGET_USED: "noetic.layer.budget.used";
+    readonly BUDGET_YIELDED: "noetic.layer.budget.yielded";
+};
+/**
+ * Runs a layer hook under its timeout and records a `layer.hook` span (or
+ * event) for it. Rethrows whatever the hook threw (or the timeout), so callers
+ * keep their own failure handling. The span opens before the hook runs and ends
+ * once it settles.
+ */
+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): Promise<void>;
+/** Runs a hook under a timeout without tracing it, for calls that must leave no trace (a peek recall). */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T>;
+export {};

package/dist/context/hook-call.js

@@ -0,0 +1,148 @@
+/**
+ * Timed, traced calls into context layer hooks. Each call of a traced hook is
+ * recorded as one `layer.hook` record shaped as a `LayerTraceSpan`: a child
+ * span of the context's span when the context can open one
+ * (`ctx.trace.createSpan`), otherwise an event on the context's span. Never
+ * both, so a backend sees each call once.
+ */
+//#endregion
+//#region Public API
+/** Name of the span (or span event) recording one layer hook call. */
+export const LAYER_HOOK_EVENT = 'layer.hook';
+/** Attributes of a `layer.hook` span. A span times itself, so it carries no duration. */
+export const LayerHookAttr = {
+    LAYER_ID: 'noetic.layer.id',
+    HOOK: 'noetic.layer.hook',
+    STATUS: 'noetic.layer.status',
+    ITEM_COUNT: 'noetic.layer.item_count',
+    BUDGET_ALLOCATED: 'noetic.layer.budget.allocated',
+    BUDGET_USED: 'noetic.layer.budget.used',
+    BUDGET_YIELDED: 'noetic.layer.budget.yielded',
+};
+/**
+ * Runs a layer hook under its timeout and records a `layer.hook` span (or
+ * event) for it. Rethrows whatever the hook threw (or the timeout), so callers
+ * keep their own failure handling. The span opens before the hook runs and ends
+ * once it settles.
+ */
+export async function callHook({ ctx, layerId, hook, timeout, run, measure, }) {
+    const span = ctx.trace.createSpan?.(LAYER_HOOK_EVENT);
+    const started = performance.now();
+    const outcome = await settle(withTimeout(run(), timeout));
+    const duration = performance.now() - started;
+    if (outcome.ok) {
+        await traceHook(ctx, span, {
+            layerId,
+            hook,
+            duration,
+            status: 'ok',
+            ...measure?.(outcome.value),
+        });
+        return outcome.value;
+    }
+    await traceHook(ctx, span, {
+        layerId,
+        hook,
+        duration,
+        status: outcome.error instanceof HookTimeout ? 'timeout' : 'error',
+        error: {
+            message: outcome.error instanceof Error ? outcome.error.message : String(outcome.error),
+        },
+    });
+    throw outcome.error;
+}
+/** Records a hook the layer defines but the lifecycle did not call. */
+export async function traceSkipped(ctx, layerId, hook) {
+    await traceHook(ctx, ctx.trace.createSpan?.(LAYER_HOOK_EVENT), {
+        layerId,
+        hook,
+        duration: 0,
+        status: 'skipped',
+    });
+}
+/** Runs a hook under a timeout without tracing it, for calls that must leave no trace (a peek recall). */
+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`);
+    }
+}
+async function settle(promise) {
+    try {
+        return {
+            ok: true,
+            value: await promise,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error,
+        };
+    }
+}
+async function traceHook(ctx, span, record) {
+    if (!span) {
+        ctx.trace.addEvent(LAYER_HOOK_EVENT, eventAttributes(record));
+        return;
+    }
+    for (const [key, value] of Object.entries(spanAttributes(record))) {
+        span.setAttribute(key, value);
+    }
+    await span.end();
+}
+function spanAttributes(record) {
+    const attributes = {
+        [LayerHookAttr.LAYER_ID]: record.layerId,
+        [LayerHookAttr.HOOK]: record.hook,
+        [LayerHookAttr.STATUS]: record.status,
+    };
+    if (record.itemCount !== undefined) {
+        attributes[LayerHookAttr.ITEM_COUNT] = record.itemCount;
+    }
+    if (record.budget) {
+        attributes[LayerHookAttr.BUDGET_ALLOCATED] = record.budget.allocated;
+        attributes[LayerHookAttr.BUDGET_USED] = record.budget.used;
+        attributes[LayerHookAttr.BUDGET_YIELDED] = record.budget.yielded;
+    }
+    if (record.error) {
+        attributes.error = true;
+        attributes['error.message'] = record.error.message;
+    }
+    return attributes;
+}
+/** Span event attributes hold only scalars, so nested fields flatten to dotted keys. */
+function eventAttributes(record) {
+    const attributes = {
+        layerId: record.layerId,
+        hook: record.hook,
+        duration: record.duration,
+        status: record.status,
+    };
+    if (record.itemCount !== undefined) {
+        attributes.itemCount = record.itemCount;
+    }
+    if (record.budget) {
+        attributes['budget.allocated'] = record.budget.allocated;
+        attributes['budget.used'] = record.budget.used;
+        attributes['budget.yielded'] = record.budget.yielded;
+    }
+    if (record.error) {
+        attributes['error.message'] = record.error.message;
+    }
+    return attributes;
+}
+//#endregion

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

@@ -1,4 +1,5 @@
 import type { ContextLayer, DecisionRecord, ExecutionContext, Item, ItemLog, ItemSchemaRegistry, LLMResponse, ScopedStorage, SteeringDecision, StorageAdapter } from '@noetic-tools/types';
+import type { LiveChild } from './parent-updates.js';
 export interface LayerStateStore {
     get<T>(executionId: string, layerId: string): T | undefined;
     set<T>(executionId: string, layerId: string, state: T): void;
@@ -13,6 +14,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 +36,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).
@@ -36,6 +45,17 @@ export interface LayerStateStore {
     disable?(executionId: string, layerId: string): void;
     /** Whether a layer was disabled for an execution. */
     isDisabled?(executionId: string, layerId: string): boolean;
+    /**
+     * Register a running child. From now on every `set()` of the parent's state
+     * for a layer is delivered to that layer's `onParentUpdate` in the child, in
+     * the background. `cleanup(childExecutionId)` forgets the child. Optional so
+     * custom stores keep compiling; without it, children get no parent updates.
+     */
+    adopt?(child: LiveChild): void;
+    /** Stop parent updates to a child and wait for deliveries already running. */
+    release?(childExecutionId: string): Promise<void>;
+    /** Number of registered children, for leak checks. */
+    liveChildren?(): number;
 }
 interface InitLayersParams {
     layers: ContextLayer[];
@@ -113,6 +133,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 +257,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,6 @@
 import { createMessage, defaultItemSchemaRegistry, estimateTokens, frameworkCast, NoeticConfigError, NoeticErrorImpl, SteeringAction, } from '@noetic-tools/types';
+import { callHook, traceSkipped, withTimeout } from './hook-call.js';
+import { createLiveChildren } from './parent-updates.js';
 import { createScopedStorage, resolveScopeKey } from './scope.js';
 /** Maximum allowed re-render depth to prevent infinite loops */
 const MAX_RERENDER_DEPTH = 3;
@@ -28,7 +30,7 @@ export function createLayerStateStore(diagnostic) {
         }
         entry.inFlight = null;
     }
-    return {
+    const store = {
         get(executionId, layerId) {
             return frameworkCast(states.get(executionId)?.get(layerId));
         },
@@ -39,6 +41,7 @@ export function createLayerStateStore(diagnostic) {
                 states.set(executionId, execMap);
             }
             execMap.set(layerId, state);
+            children.notify(executionId, layerId, state);
             const entry = durables.get(executionId)?.get(layerId);
             if (!entry) {
                 return;
@@ -87,12 +90,34 @@ export function createLayerStateStore(diagnostic) {
             return disabled.get(executionId)?.has(layerId) ?? false;
         },
         cleanup(executionId) {
+            children.drop(executionId);
             states.delete(executionId);
             durables.delete(executionId);
             disabled.delete(executionId);
         },
+        drop(executionId, layerId) {
+            states.get(executionId)?.delete(layerId);
+            durables.get(executionId)?.delete(layerId);
+            disabled.get(executionId)?.delete(layerId);
+        },
+        adopt(child) {
+            children.adopt(child);
+        },
+        release(childExecutionId) {
+            return children.release(childExecutionId);
+        },
+        liveChildren() {
+            return children.size;
+        },
         diagnostic: report,
     };
+    const children = createLiveChildren(store, (executionId, layer) => isLayerDisabled({
+        store,
+        executionId,
+        layer,
+        state: store.get(executionId, layer.id),
+    }));
+    return store;
 }
 /**
  * Whether a layer must be skipped for this execution — either explicitly
@@ -136,18 +161,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 +215,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)) {
+            await 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 +292,9 @@ export async function recallLayers({ layers, query, ctx, log, budgets, store, it
             layer,
             state: stored,
         })) {
+            if (!peek) {
+                await traceSkipped(ctx, layer.id, 'recall');
+            }
             continue; // was disabled
         }
         // Skipping the write is not enough for a peek: a hook may mutate the
@@ -281,15 +304,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 +359,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 +468,7 @@ export async function storeLayers({ layers, response, ctx, log, store, recallCac
             layer,
             state,
         })) {
+            await traceSkipped(ctx, layer.id, 'store');
             continue;
         }
         snapshots.push({
@@ -424,15 +478,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
@@ -472,14 +531,22 @@ export async function notifyDecision({ layers, record, ctx, store, recallCache,
             layer,
             state,
         })) {
+            await traceSkipped(ctx, layer.id, 'onDecision');
             continue;
         }
+        const onDecision = layer.hooks.onDecision;
         try {
-            const result = await withTimeout(layer.hooks.onDecision({
-                state,
-                record,
+            const result = await callHook({
                 ctx,
-            }), layer.timeouts?.onDecision ?? 5e3);
+                layerId: layer.id,
+                hook: 'onDecision',
+                timeout: layer.timeouts?.onDecision ?? 5e3,
+                run: () => onDecision({
+                    state,
+                    record,
+                    ctx,
+                }),
+            });
             if (result && 'state' in result) {
                 store.set(ctx.executionId, layer.id, result.state);
                 if (recallCache && layer.recallMode === 'eventual') {
@@ -493,7 +560,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 +578,20 @@ export async function disposeLayers({ layers, ctx, store }) {
             layer,
             state,
         })) {
+            await 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 +599,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 +634,40 @@ export async function spawnLayers({ layers, parentCtx, childCtx, store, itemSche
             layer,
             state: parentState,
         })) {
+            await 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;
@@ -585,6 +680,9 @@ export async function spawnLayers({ layers, parentCtx, childCtx, store, itemSche
  * `spawn_summary_failed` diagnostic plus a span event on the child's span.
  */
 export async function returnLayers({ layers, stepId, parentCtx, childCtx, childLog, result, store, }) {
+    // The child has finished: no more parent updates, and the ones in flight
+    // land before its state is merged.
+    await store.release?.(childCtx.executionId);
     const sorted = [
         ...layers,
     ].sort((a, b) => a.slot - b.slot);
@@ -599,17 +697,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) {
+            await 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 +753,23 @@ export async function completeLayers({ layers, ctx, log, outcome, store, }) {
             layer,
             state,
         })) {
+            await 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);
             }
@@ -684,17 +796,24 @@ export async function beforeToolCallLayers({ layers, toolName, toolArgs, callId,
             layer,
             state,
         })) {
+            await traceSkipped(ctx, layer.id, 'beforeToolCall');
             continue;
         }
+        const beforeToolCall = layer.hooks.beforeToolCall;
         try {
-            const timeout = layer.timeouts?.beforeToolCall ?? 5e3;
-            const result = await withTimeout(layer.hooks.beforeToolCall({
-                toolName,
-                toolArgs,
-                callId,
+            const result = await callHook({
                 ctx,
-                state,
-            }), timeout);
+                layerId: layer.id,
+                hook: 'beforeToolCall',
+                timeout: layer.timeouts?.beforeToolCall ?? 5e3,
+                run: () => beforeToolCall({
+                    toolName,
+                    toolArgs,
+                    callId,
+                    ctx,
+                    state,
+                }),
+            });
             if (result.state !== undefined) {
                 store.set(ctx.executionId, layer.id, result.state);
             }
@@ -737,15 +856,22 @@ export async function afterModelCallLayers({ layers, response, ctx, store, }) {
             layer,
             state,
         })) {
+            await traceSkipped(ctx, layer.id, 'afterModelCall');
             continue;
         }
+        const afterModelCall = layer.hooks.afterModelCall;
         try {
-            const timeout = layer.timeouts?.afterModelCall ?? 1e4;
-            const result = await withTimeout(layer.hooks.afterModelCall({
-                response,
+            const result = await callHook({
                 ctx,
-                state,
-            }), timeout);
+                layerId: layer.id,
+                hook: 'afterModelCall',
+                timeout: layer.timeouts?.afterModelCall ?? 1e4,
+                run: () => afterModelCall({
+                    response,
+                    ctx,
+                    state,
+                }),
+            });
             if (result.state !== undefined) {
                 store.set(ctx.executionId, layer.id, result.state);
             }
@@ -785,15 +911,22 @@ export async function projectHistoryLayers({ layers, items, ctx, store, }) {
             layer,
             state,
         })) {
+            await traceSkipped(ctx, layer.id, 'projectHistory');
             continue;
         }
+        const projectHistory = layer.hooks.projectHistory;
         try {
-            const timeout = layer.timeouts?.projectHistory ?? 5e3;
-            const result = await withTimeout(layer.hooks.projectHistory({
-                items: current,
+            const result = await callHook({
                 ctx,
-                state,
-            }), timeout);
+                layerId: layer.id,
+                hook: 'projectHistory',
+                timeout: layer.timeouts?.projectHistory ?? 5e3,
+                run: () => projectHistory({
+                    items: current,
+                    ctx,
+                    state,
+                }),
+            });
             current = result.items;
         }
         catch (e) {
@@ -831,16 +964,23 @@ export async function runAppendPipeline({ layers, items, ctx, log, store, }) {
             layer,
             state,
         })) {
+            await traceSkipped(ctx, layer.id, 'onItemAppend');
             continue;
         }
+        const onItemAppend = layer.hooks.onItemAppend;
         try {
-            const timeout = layer.timeouts?.onItemAppend ?? DEFAULT_ON_ITEM_APPEND_TIMEOUT;
-            const result = await withTimeout(layer.hooks.onItemAppend({
-                items: currentItems,
-                log,
+            const result = await callHook({
                 ctx,
-                state,
-            }), timeout);
+                layerId: layer.id,
+                hook: 'onItemAppend',
+                timeout: layer.timeouts?.onItemAppend ?? DEFAULT_ON_ITEM_APPEND_TIMEOUT,
+                run: () => onItemAppend({
+                    items: currentItems,
+                    log,
+                    ctx,
+                    state,
+                }),
+            });
             // Update items for next layer in pipeline
             currentItems = result.items;
             // Update state if provided

package/dist/context/parent-updates.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Live children and `onParentUpdate` delivery. A child execution is live from
+ * the moment its spawn (or inParallel path) starts running until it returns or
+ * is cleaned up. While it is live, every write of a parent layer's state is
+ * handed to the same layer's `onParentUpdate` in the child.
+ */
+import type { ContextLayer, ExecutionContext, ItemLog, ItemSchemaRegistry } from '@noetic-tools/types';
+/** @public A running child execution that receives its parent's layer writes. */
+export interface LiveChild {
+    /** Execution whose layer writes the child receives. */
+    parentExecutionId: string;
+    /** The child's execution context; hooks run on it and trace onto its span. */
+    ctx: ExecutionContext;
+    /** The layers active in the child. */
+    layers: ContextLayer[];
+    /** The child's item log, where returned items are appended. */
+    log: ItemLog;
+    itemSchemas?: ItemSchemaRegistry;
+}
+/** The slice of the layer state store that delivery reads and writes through. */
+export interface ParentUpdateStore {
+    get<T>(executionId: string, layerId: string): T | undefined;
+    set<T>(executionId: string, layerId: string, state: T): void;
+    diagnostic: (layerId: string, hook: string, error: unknown) => void;
+}
+/** Whether a layer's hooks are switched off for an execution. */
+type SkipCheck = (executionId: string, layer: ContextLayer) => boolean;
+export interface LiveChildren {
+    adopt(child: LiveChild): void;
+    /** Hands a parent write to every live child of `parentExecutionId`. */
+    notify(parentExecutionId: string, layerId: string, state: unknown): void;
+    /** Stops new deliveries to a child and waits for the ones already running. */
+    release(childExecutionId: string): Promise<void>;
+    /** Forgets a child at once; a delivery still running discards its result. */
+    drop(childExecutionId: string): void;
+    /** Number of live children, for leak checks. */
+    readonly size: number;
+}
+/**
+ * Builds the live-child registry a layer state store dispatches through.
+ * `store` is read lazily, so it may be the object under construction.
+ */
+export declare function createLiveChildren(store: ParentUpdateStore, skips: SkipCheck): LiveChildren;
+export {};

package/dist/context/parent-updates.js

@@ -0,0 +1,117 @@
+/**
+ * Live children and `onParentUpdate` delivery. A child execution is live from
+ * the moment its spawn (or inParallel path) starts running until it returns or
+ * is cleaned up. While it is live, every write of a parent layer's state is
+ * handed to the same layer's `onParentUpdate` in the child.
+ */
+import { defaultItemSchemaRegistry } from '@noetic-tools/types';
+import { callHook } from './hook-call.js';
+//#endregion
+//#region Public API
+const DEFAULT_TIMEOUT = 5e3;
+/**
+ * Builds the live-child registry a layer state store dispatches through.
+ * `store` is read lazily, so it may be the object under construction.
+ */
+export function createLiveChildren(store, skips) {
+    const byChild = new Map();
+    const byParent = new Map();
+    function forget(childExecutionId) {
+        const entry = byChild.get(childExecutionId);
+        if (!entry) {
+            return undefined;
+        }
+        byChild.delete(childExecutionId);
+        const siblings = byParent.get(entry.child.parentExecutionId);
+        siblings?.delete(entry);
+        if (siblings?.size === 0) {
+            byParent.delete(entry.child.parentExecutionId);
+        }
+        entry.open = false;
+        return entry;
+    }
+    return {
+        adopt(child) {
+            const entry = {
+                child,
+                queue: Promise.resolve(),
+                open: true,
+                gone: false,
+            };
+            byChild.set(child.ctx.executionId, entry);
+            let siblings = byParent.get(child.parentExecutionId);
+            if (!siblings) {
+                siblings = new Set();
+                byParent.set(child.parentExecutionId, siblings);
+            }
+            siblings.add(entry);
+        },
+        notify(parentExecutionId, layerId, state) {
+            const siblings = byParent.get(parentExecutionId);
+            if (!siblings) {
+                return;
+            }
+            for (const entry of siblings) {
+                const layer = entry.child.layers.find((l) => l.id === layerId);
+                if (!layer?.hooks.onParentUpdate) {
+                    continue;
+                }
+                entry.queue = entry.queue.then(() => deliver({
+                    entry,
+                    layer,
+                    parentState: state,
+                    store,
+                    skips,
+                }));
+            }
+        },
+        async release(childExecutionId) {
+            const entry = forget(childExecutionId);
+            await entry?.queue;
+        },
+        drop(childExecutionId) {
+            const entry = forget(childExecutionId);
+            if (entry) {
+                entry.gone = true;
+            }
+        },
+        get size() {
+            return byChild.size;
+        },
+    };
+}
+/** Runs one `onParentUpdate` call. Never rejects: failures become diagnostics. */
+async function deliver({ entry, layer, parentState, store, skips }) {
+    const { ctx, log, itemSchemas = defaultItemSchemaRegistry } = entry.child;
+    const onParentUpdate = layer.hooks.onParentUpdate;
+    if (!entry.open || !onParentUpdate || skips(ctx.executionId, layer)) {
+        return;
+    }
+    try {
+        const result = await callHook({
+            ctx,
+            layerId: layer.id,
+            hook: 'onParentUpdate',
+            timeout: layer.timeouts?.onParentUpdate ?? DEFAULT_TIMEOUT,
+            run: () => onParentUpdate({
+                parentState,
+                childState: store.get(ctx.executionId, layer.id),
+                childCtx: ctx,
+            }),
+        });
+        // A child cleaned up mid-call has no state left to write into.
+        if (!result || entry.gone) {
+            return;
+        }
+        if ('childState' in result) {
+            store.set(ctx.executionId, layer.id, result.childState);
+        }
+        for (const item of itemSchemas.extend(layer.itemSchemas).parseMany(result.items ?? [])) {
+            log.append(item);
+        }
+    }
+    catch (e) {
+        store.diagnostic(layer.id, 'onParentUpdate', e);
+    }
+}
+//#endregion

package/dist/context/span-export.d.ts

@@ -0,0 +1,7 @@
+import type { Span, TraceExporter } from '@noetic-tools/types';
+/**
+ * Hands ended spans to `exporter` without letting it fail the traced work: a
+ * rejecting (or throwing) exporter is reported once as a warning and
+ * swallowed, so tracing never changes what a hook, step, or call returns.
+ */
+export declare function exportSpans(exporter: TraceExporter, spans: Span[]): Promise<void>;

package/dist/context/span-export.js

@@ -0,0 +1,13 @@
+/**
+ * Hands ended spans to `exporter` without letting it fail the traced work: a
+ * rejecting (or throwing) exporter is reported once as a warning and
+ * swallowed, so tracing never changes what a hook, step, or call returns.
+ */
+export async function exportSpans(exporter, spans) {
+    try {
+        await exporter.export(spans);
+    }
+    catch (error) {
+        console.warn('[noetic] trace export failed; the traced work is unaffected:', error);
+    }
+}

package/dist/index.d.ts

@@ -3,12 +3,13 @@
  * ContextLayer contract, lifecycle/budget/projection machinery, and built-in
  * layer implementations.
  */
-export type { ContextScope, ExecutionContext, ExecutionOutcome, LayerCallModelRequest, } from '@noetic-tools/types';
+export type { ContextScope, ExecutionContext, ExecutionOutcome, ExecutionSpan, LayerCallModelRequest, } from '@noetic-tools/types';
 export * from '@noetic-tools/types/contract';
 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, LayerHookAttr } from './context/hook-call.js';
 export * from './context/layer-api.js';
 export * from './context/layer-lifecycle.js';
 export * from './context/layer-provides.js';
@@ -24,7 +25,9 @@ export * from './context/layers/steering.js';
 export * from './context/layers/task-state.js';
 export * from './context/layers/temporal.js';
 export * from './context/layers/tool-calls.js';
+export type { LiveChild } from './context/parent-updates.js';
 export * from './context/projector.js';
 export * from './context/scope.js';
+export * from './context/span-export.js';
 export * from './context/storage-batch.js';
 export * from './context/strip-unresolved.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, LayerHookAttr } from './context/hook-call.js';
 export * from './context/layer-api.js';
 export * from './context/layer-lifecycle.js';
 export * from './context/layer-provides.js';
@@ -28,5 +29,6 @@ export * from './context/layers/temporal.js';
 export * from './context/layers/tool-calls.js';
 export * from './context/projector.js';
 export * from './context/scope.js';
+export * from './context/span-export.js';
 export * from './context/storage-batch.js';
 export * from './context/strip-unresolved.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/context",
-  "version": "1.6.0",
+  "version": "1.8.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.9.0",
     "zod": "^4.0.0"
   },
   "scripts": {