@noetic-tools/context 1.3.0 → 1.5.0

package/dist/context/budget.d.ts

@@ -9,6 +9,13 @@ export interface BudgetAllocation {
  * `step.projection` to match the target model's real context length.
  */
 export declare const DEFAULT_PROJECTION: ProjectionPolicy;
+/**
+ * Default view budget for `decide` steps. Decision models degrade on long
+ * state — TypeSafe Jev drops to a slower, less accurate long-context mode above
+ * about 32 KB of text — so a decision sees a tighter window than a chat turn.
+ * @public
+ */
+export declare const DECISION_PROJECTION: ProjectionPolicy;
 interface AllocateBudgetsOpts {
     layers: ContextLayer[];
     totalBudget: number;

package/dist/context/budget.js

@@ -9,6 +9,17 @@ export const DEFAULT_PROJECTION = {
     responseReserve: 4e3,
     overflow: 'sliding_window',
 };
+/**
+ * Default view budget for `decide` steps. Decision models degrade on long
+ * state — TypeSafe Jev drops to a slower, less accurate long-context mode above
+ * about 32 KB of text — so a decision sees a tighter window than a chat turn.
+ * @public
+ */
+export const DECISION_PROJECTION = {
+    tokenBudget: 8e3,
+    responseReserve: 0,
+    overflow: 'truncate',
+};
 function extractMin(config) {
     if (config && typeof config === 'object' && 'min' in config) {
         return config.min;

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

@@ -1,4 +1,4 @@
-import type { ContextLayer, ExecutionContext, Item, ItemLog, ItemSchemaRegistry, LLMResponse, ScopedStorage, SteeringDecision, StorageAdapter } from '@noetic-tools/types';
+import type { ContextLayer, DecisionRecord, ExecutionContext, Item, ItemLog, ItemSchemaRegistry, LLMResponse, ScopedStorage, SteeringDecision, StorageAdapter } from '@noetic-tools/types';
 export interface LayerStateStore {
     get<T>(executionId: string, layerId: string): T | undefined;
     set<T>(executionId: string, layerId: string, state: T): void;
@@ -42,6 +42,12 @@ interface InitLayersParams {
     ctx: ExecutionContext;
     storage: StorageAdapter;
     store: LayerStateStore;
+    /**
+     * Skip `init` for layers that already hold state for this execution. Set for
+     * an execution restored from a checkpoint, whose snapshot state `init` would
+     * otherwise overwrite with a fresh start.
+     */
+    keep?: boolean;
 }
 interface RecallLayersParams {
     layers: ContextLayer[];
@@ -51,6 +57,8 @@ interface RecallLayersParams {
     budgets: Map<string, number>;
     store: LayerStateStore;
     itemSchemas?: ItemSchemaRegistry;
+    /** Render without committing returned state. See `RecallOptions.peek`. */
+    peek?: boolean;
 }
 interface StoreLayersParams {
     layers: ContextLayer[];
@@ -172,8 +180,8 @@ export interface RecallCache {
 }
 export declare function createRecallCache(): RecallCache;
 export declare function mostRestrictive(decisions: SteeringDecision[]): SteeringDecision;
-export declare function initLayers({ layers, ctx, storage, store }: InitLayersParams): Promise<void>;
-export declare function recallLayers({ layers, query, ctx, log, budgets, store, itemSchemas, }: RecallLayersParams): Promise<RecallEntry[]>;
+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 = {
     layerId: string;
     items: Item[];
@@ -202,6 +210,19 @@ interface RecallLayersEventualParams extends RecallLayersModeParams {
  */
 export declare function recallLayersEventual({ cache, forceAtomic, ...params }: RecallLayersEventualParams): Promise<RecallEntry[]>;
 export declare function storeLayers({ layers, response, ctx, log, store, recallCache, }: StoreLayersParams): Promise<void>;
+interface NotifyDecisionParams {
+    layers: ContextLayer[];
+    record: DecisionRecord;
+    ctx: ExecutionContext;
+    store: LayerStateStore;
+    recallCache?: RecallCache;
+}
+/**
+ * Run each layer's `onDecision` hook in slot order. Sequential, unlike
+ * `storeLayers`: decisions are small and ordered, and a later layer may read
+ * 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 spawnLayers({ layers, parentCtx, childCtx, store, itemSchemas, storage, }: SpawnLayersParams): Promise<{
     layerId: string;

package/dist/context/layer-lifecycle.js

@@ -179,12 +179,15 @@ function layerItemSchemas(layer, base = defaultItemSchemaRegistry) {
 }
 //#endregion
 //#region Public API
-export async function initLayers({ layers, ctx, storage, store }) {
+export async function initLayers({ layers, ctx, storage, store, keep = false, }) {
     // Sequential, array order
     for (const layer of layers) {
         if (!layer.hooks.init) {
             continue;
         }
+        if (keep && store.has?.(ctx.executionId, layer.id)) {
+            continue;
+        }
         const scopeKey = resolveScopeKey(layer.scope, ctx);
         const scopedStorage = createScopedStorage(storage, layer.id, scopeKey);
         try {
@@ -236,7 +239,7 @@ function registerDurableTargets({ layers, ctx, storage, store, }) {
         store.registerDurable(ctx.executionId, layer.id, createScopedStorage(storage, layer.id, scopeKey));
     }
 }
-export async function recallLayers({ layers, query, ctx, log, budgets, store, itemSchemas = defaultItemSchemaRegistry, }) {
+export async function recallLayers({ layers, query, ctx, log, budgets, store, itemSchemas = defaultItemSchemaRegistry, peek = false, }) {
     const sorted = [
         ...layers,
     ].sort((a, b) => a.slot - b.slot);
@@ -245,15 +248,21 @@ export async function recallLayers({ layers, query, ctx, log, budgets, store, it
         if (!layer.hooks.recall) {
             continue;
         }
-        const state = store.get(ctx.executionId, layer.id);
+        const stored = store.get(ctx.executionId, layer.id);
         if (isLayerDisabled({
             store,
             executionId: ctx.executionId,
             layer,
-            state,
+            state: stored,
         })) {
             continue; // was disabled
         }
+        // Skipping the write is not enough for a peek: a hook may mutate the
+        // stored object in place (steering splices its queue), so it gets a copy.
+        const state = peek ? copyForPeek(stored) : stored;
+        if (peek && state === PEEK_UNSAFE) {
+            continue;
+        }
         const budget = budgets.get(layer.id) ?? 0;
         try {
             const timeout = layer.timeouts?.recall ?? 5e3;
@@ -287,7 +296,7 @@ export async function recallLayers({ layers, query, ctx, log, budgets, store, it
                 tokenCount: result.tokenCount,
                 mutatedState,
             });
-            if (mutatedState) {
+            if (mutatedState && !peek) {
                 store.set(ctx.executionId, layer.id, result.state);
             }
         }
@@ -297,6 +306,16 @@ export async function recallLayers({ layers, query, ctx, log, budgets, store, it
     }
     return results;
 }
+const PEEK_UNSAFE = Symbol('peek-unsafe');
+/** A deep copy, or `PEEK_UNSAFE` when the state cannot be copied (it holds functions). */
+function copyForPeek(state) {
+    try {
+        return structuredClone(state);
+    }
+    catch {
+        return PEEK_UNSAFE;
+    }
+}
 /**
  * Recall the layers that must complete before the model call: those with
  * `recallMode !== 'eventual'`, or every layer when `forceAtomic` is set.
@@ -330,6 +349,17 @@ export async function recallLayersEventual({ cache, forceAtomic, ...params }) {
         const key = recallCacheKey(layer, params.ctx);
         const cached = cache.entries.get(key);
         const isStale = cache.stale.has(key);
+        // A peek renders a cold or stale layer but leaves the cache as it found it,
+        // so the next real recall still sees the entry as needing a render.
+        if (params.peek && (!cached || isStale)) {
+            results.push(...(await recallLayers({
+                ...params,
+                layers: [
+                    layer,
+                ],
+            })));
+            continue;
+        }
         if (!cached || isStale) {
             const recalled = await recallLayers({
                 ...params,
@@ -405,6 +435,47 @@ export async function storeLayers({ layers, response, ctx, log, store, recallCac
     }));
     await store.flush?.(ctx.executionId);
 }
+/**
+ * Run each layer's `onDecision` hook in slot order. Sequential, unlike
+ * `storeLayers`: decisions are small and ordered, and a later layer may read
+ * what an earlier one recorded.
+ */
+export async function notifyDecision({ layers, record, ctx, store, recallCache, }) {
+    const sorted = [
+        ...layers,
+    ].sort((a, b) => a.slot - b.slot);
+    for (const layer of sorted) {
+        if (!layer.hooks.onDecision) {
+            continue;
+        }
+        const state = store.get(ctx.executionId, layer.id);
+        if (isLayerDisabled({
+            store,
+            executionId: ctx.executionId,
+            layer,
+            state,
+        })) {
+            continue;
+        }
+        try {
+            const result = await withTimeout(layer.hooks.onDecision({
+                state,
+                record,
+                ctx,
+            }), layer.timeouts?.onDecision ?? 5e3);
+            if (result && 'state' in result) {
+                store.set(ctx.executionId, layer.id, result.state);
+                if (recallCache && layer.recallMode === 'eventual') {
+                    recallCache.stale.add(recallCacheKey(layer, ctx));
+                }
+            }
+        }
+        catch (e) {
+            store.diagnostic(layer.id, 'onDecision', e);
+        }
+    }
+    await store.flush?.(ctx.executionId);
+}
 export async function disposeLayers({ layers, ctx, store }) {
     // Sequential, REVERSE array order
     const reversed = [

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

@@ -0,0 +1,50 @@
+import type { ContextScope, DecisionRecord, InitParams, InitResult, LayerDataDecl, OnDecisionParams, RecallParams, ReturnParams, ReturnResult, SpawnParams, SpawnResult } from '@noetic-tools/types';
+/** @public Configuration for {@link decisionsHistoryLayer}. */
+export interface DecisionsHistoryConfig<Id extends string = 'decisionsHistory'> {
+    /** Layer id, and so the `ctx.context` key. Default `'decisionsHistory'`. */
+    id?: Id;
+    /** Default `'execution'`. With `'thread'` or `'resource'`, history persists across runs. */
+    scope?: ContextScope;
+    /** Records kept; the oldest drop first. Default 50. */
+    maxRecords?: number;
+    /** Render a summary of the latest decisions into the view. Default true. */
+    recall?: boolean;
+    /** Default `Slot.WORKING_MEMORY + 10`. */
+    slot?: number;
+}
+/** @public State held by {@link decisionsHistoryLayer}: records, oldest first. */
+export interface DecisionsHistoryState {
+    records: DecisionRecord[];
+}
+/** @public The layer {@link decisionsHistoryLayer} returns, with its literal id kept for `ctx.context` typing. */
+export interface DecisionsHistoryLayer<Id extends string> {
+    readonly id: Id;
+    name: string;
+    slot: number;
+    scope: ContextScope;
+    provides: {
+        latest: LayerDataDecl<Readonly<Record<string, DecisionRecord>>, DecisionsHistoryState>;
+        all: LayerDataDecl<ReadonlyArray<DecisionRecord>, DecisionsHistoryState>;
+    };
+    hooks: {
+        init(params: InitParams): Promise<InitResult<DecisionsHistoryState>>;
+        recall(params: RecallParams<DecisionsHistoryState>): Promise<string | null>;
+        onDecision(params: OnDecisionParams<DecisionsHistoryState>): Promise<{
+            state: DecisionsHistoryState;
+        }>;
+        onSpawn(params: SpawnParams<DecisionsHistoryState>): Promise<SpawnResult<DecisionsHistoryState>>;
+        onReturn(params: ReturnParams<DecisionsHistoryState>): Promise<ReturnResult<DecisionsHistoryState>>;
+    };
+}
+/**
+ * A context layer that records every `decide` step's answers. Later steps read
+ * them through `ctx.context.decisionsHistory.latest[stepId]`, and later `callModel`
+ * steps see a one-line-per-decision summary in their view. inParallel paths and spawn
+ * children start with the parent's records and hand their new ones back.
+ *
+ * @public
+ */
+export declare function decisionsHistoryLayer(config?: Omit<DecisionsHistoryConfig, 'id'>): DecisionsHistoryLayer<'decisionsHistory'>;
+export declare function decisionsHistoryLayer<const Id extends string>(config: DecisionsHistoryConfig<Id> & {
+    id: Id;
+}): DecisionsHistoryLayer<Id>;

package/dist/context/layers/decisions-history.js

@@ -0,0 +1,111 @@
+import { frameworkCast, Slot } from '@noetic-tools/types';
+import { layerData } from '../layer-provides.js';
+//#endregion
+//#region Public API
+const DEFAULT_MAX_RECORDS = 50;
+export function decisionsHistoryLayer(config) {
+    const maxRecords = config?.maxRecords ?? DEFAULT_MAX_RECORDS;
+    const renders = config?.recall ?? true;
+    const keep = (records) => ({
+        records: records.slice(-maxRecords),
+    });
+    return {
+        id: config?.id ?? 'decisionsHistory',
+        name: 'Decisions History',
+        slot: config?.slot ?? Slot.WORKING_MEMORY + 10,
+        scope: config?.scope ?? 'execution',
+        provides: {
+            latest: layerData({
+                read: (state) => latestByStep(state.records),
+            }),
+            all: layerData({
+                read: (state) => state.records,
+            }),
+        },
+        hooks: {
+            async init({ storage }) {
+                const saved = await storage.get('state');
+                return {
+                    state: saved ?? {
+                        records: [],
+                    },
+                };
+            },
+            async recall({ state }) {
+                if (!renders || state.records.length === 0) {
+                    return null;
+                }
+                return renderSummary(latestByStep(state.records));
+            },
+            async onDecision({ state, record }) {
+                return {
+                    state: keep([
+                        ...state.records,
+                        record,
+                    ]),
+                };
+            },
+            async onSpawn({ parentState }) {
+                return {
+                    childState: {
+                        records: [
+                            ...parentState.records,
+                        ],
+                    },
+                };
+            },
+            // Concurrent fork paths each return; merging only the records the parent
+            // lacks keeps every sibling's decisions.
+            async onReturn({ parentState, childState }) {
+                const known = new Set(parentState.records.map(recordKey));
+                const added = childState.records.filter((r) => !known.has(recordKey(r)));
+                return {
+                    parentState: keep([
+                        ...parentState.records,
+                        ...added,
+                    ]),
+                };
+            },
+        },
+    };
+}
+//#endregion
+//#region Helpers
+function recordKey(record) {
+    return `${record.stepId}\u0000${record.at}\u0000${record.modelId}`;
+}
+function latestByStep(records) {
+    const latest = {};
+    for (const record of records) {
+        latest[record.stepId] = record;
+    }
+    return latest;
+}
+function renderSummary(latest) {
+    const lines = Object.values(latest).map((record) => {
+        const answers = Object.entries(record.answers)
+            .map(([id, answer]) => `${id}=${renderAnswer(answer)}`)
+            .join(', ');
+        return `- ${record.stepId}: ${answers}`;
+    });
+    return [
+        'Decisions so far:',
+        ...lines,
+    ].join('\n');
+}
+function renderAnswer(answer) {
+    switch (answer.type) {
+        case 'boolean':
+            return `${answer.value ? 'yes' : 'no'} (${round(answer.probability)})`;
+        case 'choice':
+            return `${answer.value} (${round(frameworkCast(answer.probabilities)[answer.value] ?? 0)})`;
+        case 'score':
+            return `${answer.level} (${round(answer.value)})`;
+        case 'refusal':
+            return 'refused';
+    }
+}
+function round(n) {
+    return Math.round(n * 100) / 100;
+}
+//#endregion

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/dist/index.d.ts

@@ -13,6 +13,7 @@ export * from './context/layer-api.js';
 export * from './context/layer-lifecycle.js';
 export * from './context/layer-provides.js';
 export * from './context/layer-usage.js';
+export * from './context/layers/decisions-history.js';
 export * from './context/layers/filesystem.js';
 export * from './context/layers/history.js';
 export * from './context/layers/instructions.js';

package/dist/index.js

@@ -15,6 +15,7 @@ export * from './context/layer-api.js';
 export * from './context/layer-lifecycle.js';
 export * from './context/layer-provides.js';
 export * from './context/layer-usage.js';
+export * from './context/layers/decisions-history.js';
 export * from './context/layers/filesystem.js';
 export * from './context/layers/history.js';
 export * from './context/layers/instructions.js';

package/package.json

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