@noetic-tools/context 1.5.0 → 1.6.0

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

@@ -90,6 +90,12 @@ interface SpawnLayersParams {
 }
 interface ReturnLayersParams<T = unknown> {
     layers: ContextLayer[];
+    /**
+     * Id of the spawn (or inParallel) step whose child is returning. Names the
+     * step in `spawn_summary_failed` diagnostics; defaults to the child's
+     * execution id.
+     */
+    stepId?: string;
     parentCtx: ExecutionContext;
     childCtx: ExecutionContext;
     childLog: ItemLog;
@@ -180,6 +186,8 @@ export interface RecallCache {
 }
 export declare function createRecallCache(): RecallCache;
 export declare function mostRestrictive(decisions: SteeringDecision[]): SteeringDecision;
+/** Span event added to the child's span when a layer's `onReturn` hook fails. */
+export declare const SPAWN_SUMMARY_FAILED_EVENT = "spawn.summary_failed";
 export declare function initLayers({ layers, ctx, storage, store, keep, }: InitLayersParams): Promise<void>;
 export declare function recallLayers({ layers, query, ctx, log, budgets, store, itemSchemas, peek, }: RecallLayersParams): Promise<RecallEntry[]>;
 type RecallEntry = {
@@ -229,7 +237,14 @@ export declare function spawnLayers({ layers, parentCtx, childCtx, store, itemSc
     childState: unknown;
     items: Item[];
 }[]>;
-export declare function returnLayers<T>({ layers, parentCtx, childCtx, childLog, result, store, }: ReturnLayersParams<T>): Promise<T>;
+/**
+ * Pipes a child's result through each layer's `onReturn` hook in slot order.
+ *
+ * A failing hook never fails the spawn: the child's work already succeeded,
+ * so the result passes on unchanged and the failure is reported as a
+ * `spawn_summary_failed` diagnostic plus a span event on the child's span.
+ */
+export declare function returnLayers<T>({ layers, stepId, parentCtx, childCtx, childLog, result, store, }: ReturnLayersParams<T>): Promise<T>;
 export declare function completeLayers({ layers, ctx, log, outcome, store, }: CompleteLayersParams): Promise<void>;
 export declare function beforeToolCallLayers({ layers, toolName, toolArgs, callId, ctx, store, }: BeforeToolCallLayersParams): Promise<SteeringDecision>;
 export declare function afterModelCallLayers({ layers, response, ctx, store, }: AfterModelCallLayersParams): Promise<SteeringDecision>;

package/dist/context/layer-lifecycle.js

@@ -1,4 +1,4 @@
-import { createMessage, defaultItemSchemaRegistry, estimateTokens, frameworkCast, NoeticConfigError, SteeringAction, } from '@noetic-tools/types';
+import { createMessage, defaultItemSchemaRegistry, estimateTokens, frameworkCast, NoeticConfigError, NoeticErrorImpl, SteeringAction, } from '@noetic-tools/types';
 import { createScopedStorage, resolveScopeKey } from './scope.js';
 /** Maximum allowed re-render depth to prevent infinite loops */
 const MAX_RERENDER_DEPTH = 3;
@@ -177,6 +177,23 @@ export function mostRestrictive(decisions) {
 function layerItemSchemas(layer, base = defaultItemSchemaRegistry) {
     return base.extend(layer.itemSchemas);
 }
+/** Span event added to the child's span when a layer's `onReturn` hook fails. */
+export const SPAWN_SUMMARY_FAILED_EVENT = 'spawn.summary_failed';
+function reportSummaryFailure({ layerId, stepId, childOutput, cause, childCtx, store, }) {
+    const summaryCause = cause instanceof Error ? cause : new Error(String(cause));
+    const error = new NoeticErrorImpl({
+        kind: 'spawn_summary_failed',
+        stepId,
+        childOutput,
+        summaryCause,
+    });
+    childCtx.trace.addEvent(SPAWN_SUMMARY_FAILED_EVENT, {
+        stepId,
+        layerId,
+        message: summaryCause.message,
+    });
+    store.diagnostic(layerId, 'onReturn', error);
+}
 //#endregion
 //#region Public API
 export async function initLayers({ layers, ctx, storage, store, keep = false, }) {
@@ -560,7 +577,14 @@ export async function spawnLayers({ layers, parentCtx, childCtx, store, itemSche
     }
     return results;
 }
-export async function returnLayers({ layers, parentCtx, childCtx, childLog, result, store, }) {
+/**
+ * Pipes a child's result through each layer's `onReturn` hook in slot order.
+ *
+ * A failing hook never fails the spawn: the child's work already succeeded,
+ * so the result passes on unchanged and the failure is reported as a
+ * `spawn_summary_failed` diagnostic plus a span event on the child's span.
+ */
+export async function returnLayers({ layers, stepId, parentCtx, childCtx, childLog, result, store, }) {
     const sorted = [
         ...layers,
     ].sort((a, b) => a.slot - b.slot);
@@ -594,7 +618,14 @@ export async function returnLayers({ layers, parentCtx, childCtx, childLog, resu
             }
         }
         catch (e) {
-            store.diagnostic(layer.id, 'onReturn', e);
+            reportSummaryFailure({
+                layerId: layer.id,
+                stepId: stepId ?? childCtx.executionId,
+                childOutput: currentResult,
+                cause: e,
+                childCtx,
+                store,
+            });
         }
     }
     // The child execution's store is typically cleaned up right after onReturn —

package/dist/context/layers/history.d.ts

@@ -27,5 +27,6 @@ export interface HistoryConfig {
  * @public
  * @param config - Optional `{ maxItems }`. Defaults to 40.
  * @returns A `ContextLayer` that contributes only a `projectHistory` hook.
+ * @throws `NoeticConfigError` with code `INVALID_HISTORY_MAX_ITEMS` if `maxItems` is not an integer in the allowed range.
  */
 export declare function history(config?: HistoryConfig): ContextLayer<null>;

package/dist/context/layers/history.js

@@ -100,6 +100,7 @@ function findHeadAnchor(items, windowStart) {
  * @public
  * @param config - Optional `{ maxItems }`. Defaults to 40.
  * @returns A `ContextLayer` that contributes only a `projectHistory` hook.
+ * @throws `NoeticConfigError` with code `INVALID_HISTORY_MAX_ITEMS` if `maxItems` is not an integer in the allowed range.
  */
 export function history(config) {
     const maxItems = config?.maxItems ?? DEFAULT_MAX_ITEMS;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/context",
-  "version": "1.5.0",
+  "version": "1.6.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.6.0",
+    "@noetic-tools/types": "^3.7.0",
     "zod": "^4.0.0"
   },
   "scripts": {