@noetic-tools/context 1.4.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/dist/context/layers/observations.d.ts

@@ -19,10 +19,10 @@ export interface ObservationsConfig {
  * @returns A `ContextLayer` that accumulates and summarizes observations over time.
  */
 export declare function observations(config?: ObservationsConfig): {
-    id: 'observations';
+    id: "observations";
     name: string;
     slot: 200;
-    scope: "resource" | "thread";
+    scope: "thread" | "resource";
     budget: {
         min: number;
         max: number;

package/dist/context/layers/plan-prompts.d.ts

@@ -17,9 +17,9 @@ import type { PlanState } from './plan-state.js';
 /** How the planning briefing shapes the turn. */
 export declare const PlanStyle: {
     /** Explore → design → review → write → exit. Best when the work's shape is known. */
-    readonly Phased: 'phased';
+    readonly Phased: "phased";
     /** Explore → write → ask, on repeat. Best when requirements are still vague. */
-    readonly Interview: 'interview';
+    readonly Interview: "interview";
 };
 export type PlanStyle = (typeof PlanStyle)[keyof typeof PlanStyle];
 export interface PlanningPromptOptions {

package/dist/context/layers/plan-state.d.ts

@@ -5,11 +5,11 @@ import type { WorkflowDocument } from '@noetic-tools/types';
  * both depend on it without importing each other.
  */
 export declare const PlanPhase: {
-    readonly Idle: 'idle';
-    readonly Planning: 'planning';
-    readonly Executing: 'executing';
-    readonly Completed: 'completed';
-    readonly Failed: 'failed';
+    readonly Idle: "idle";
+    readonly Planning: "planning";
+    readonly Executing: "executing";
+    readonly Completed: "completed";
+    readonly Failed: "failed";
 };
 export type PlanPhase = (typeof PlanPhase)[keyof typeof PlanPhase];
 export interface PlanExecutionEntry {

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

@@ -14,10 +14,10 @@ export interface ScratchpadConfig {
  * @returns A `ContextLayer` providing scratchpad state the model can read and write.
  */
 export declare function scratchpad(config?: ScratchpadConfig): {
-    id: 'scratchpad';
+    id: "scratchpad";
     name: string;
     slot: 100;
-    scope: "resource" | "thread";
+    scope: "thread" | "resource";
     budget: {
         min: number;
         max: number;

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

@@ -7,7 +7,7 @@ import type { AfterModelCallParams, BeforeToolCallParams, ContextScope, LedgerEn
  * @returns A `ContextLayer` that enforces steering rules via allow/deny/guide decisions.
  */
 export declare function steering(config: SteeringConfig): {
-    id: 'steering';
+    id: "steering";
     name: string;
     slot: 90;
     scope: ContextScope;

package/dist/context/layers/task-state.d.ts

@@ -46,7 +46,7 @@ export interface TaskStateOptions {
  * @returns A `ContextLayer` scoped to the thread with durable task state.
  */
 export declare function taskState(opts?: TaskStateOptions): {
-    id: 'task-state';
+    id: "task-state";
     name: string;
     slot: number;
     scope: "thread";
@@ -93,7 +93,6 @@ export declare function taskState(opts?: TaskStateOptions): {
         }>;
         onComplete({ state, outcome, ctx }: import("@noetic-tools/types").CompleteParams<TaskState>): Promise<{
             state: {
-                files: string[];
                 data: {
                     __outcome: import("@noetic-tools/types").ExecutionOutcome;
                 };
@@ -101,6 +100,7 @@ export declare function taskState(opts?: TaskStateOptions): {
                     timestamp: number;
                     depth: number;
                 }[];
+                files: string[];
             };
         } | undefined>;
     };

package/package.json

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