@noetic-tools/core 3.1.0 → 4.0.0

package/dist/harness/agent-harness.d.ts

@@ -1,14 +1,16 @@
 import { ItemSchemaRegistry } from '@noetic-tools/types';
+import type { LayerStateStore, RecallCache } from './deps/context.js';
 import type { DetachedSpawnOverrides } from './deps/interpreter.js';
-import type { LayerStateStore, RecallCache } from './deps/memory.js';
-import type { CheckpointStore, EventBroadcaster, RestoreCheckpointOptions, StepLedgerStore } from './deps/runtime.js';
-import type { AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, Channel, ChannelHandle, Context, ContextMemory, CwdState, DeliveryMode, DetachedHandle, ExecuteInput, ExecuteOptions, ExternalChannel, FsAdapter, HarnessResponse, HarnessStatus, Item, ItemSchemaExtensions, LLMResponse, LlmProviderConfig, MemoryLayer, ProjectionPolicy, RecallLayerOutput, SessionScope, ShellAdapter, Span, SteeringDecision, Step, StorageAdapter, StreamEvent, StreamingItem, SubHarnessSession, SubprocessAdapter, Tool, TraceExporter, ZodType } from './deps/types.js';
+import type { CheckpointStore, EventBroadcaster, RestoreCheckpointOptions, StepLedgerRetention, StepLedgerStore } from './deps/runtime.js';
+import type { AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, Channel, ChannelHandle, Context, ContextData, ContextLayer, CwdState, DeliveryMode, DetachedHandle, ExecuteInput, ExecuteOptions, ExternalChannel, FsAdapter, HarnessResponse, HarnessStatus, Item, ItemSchemaExtensions, LLMResponse, LlmProviderConfig, ProjectionPolicy, RecallLayerOutput, SessionScope, ShellAdapter, Span, SteeringDecision, Step, StorageAdapter, StreamEvent, StreamingItem, SubHarnessSession, SubprocessAdapter, Tool, TraceExporter, ZodType } from './deps/types.js';
 export { createStreamIdleWatchdog } from './model-call.js';
 interface AgentHarnessOpts<TParams extends Record<string, unknown> = Record<string, unknown>> {
     name: string;
-    initialStep?: Step<ContextMemory, string, string>;
-    /** Default memory layers applied to every context created via `createContext()` / `execute()`. */
-    memory?: MemoryLayer[];
+    initialStep?: Step<ContextData, string, string>;
+    /** Default context layers applied to every context created via `createContext()` / `execute()`. */
+    context?: ContextLayer[];
+    /** @deprecated Renamed to `context`. */
+    memory?: ContextLayer[];
     storage?: StorageAdapter;
     hooks?: AgentHooks;
     /**
@@ -33,6 +35,14 @@ interface AgentHarnessOpts<TParams extends Record<string, unknown> = Record<stri
      * to enable durable execution.
      */
     checkpointStore?: CheckpointStore;
+    /**
+     * Bounds on the step-completion ledger that backs step-level resume. Only meaningful
+     * alongside a `checkpointStore`. Defaults to `DEFAULT_STEP_LEDGER_RETENTION` — 128 KiB
+     * per entry, 1000 entries per execution — so an unbounded run cannot grow an unbounded
+     * ledger. Exceeding either cap costs resumability for the affected steps (they re-run),
+     * never correctness.
+     */
+    stepLedgerRetention?: StepLedgerRetention;
     llm?: LlmProviderConfig;
     /** Harness-wide item schema extensions. */
     itemSchemas?: ItemSchemaExtensions;
@@ -85,8 +95,8 @@ export interface ResolvedLlmClient {
  */
 export declare function resolveLlmClient(config: LlmProviderConfig | undefined, env: LlmEnv): ResolvedLlmClient | undefined;
 /**
- * Default agent harness for executing agent steps with built-in channel, memory, and trace support.
- * Provides channel store, memory layer lifecycle, and trace export with no external dependencies.
+ * Default agent harness for executing agent steps with built-in channel, context, and trace support.
+ * Provides channel store, context layer lifecycle, and trace export with no external dependencies.
  *
  * Messages submitted via `execute()` are enqueued on a per-thread session and
  * processed by a `SessionRunner`. Consumers observe responses via the session-
@@ -111,13 +121,19 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
      * @internal
      */
     readonly stepLedgerStore?: StepLedgerStore;
+    /**
+     * Resolved retention bounds for that ledger. Validated at construction so a bad cap
+     * is a loud config error rather than a run that silently records nothing.
+     * @internal
+     */
+    readonly stepLedgerRetention: Required<StepLedgerRetention>;
     private readonly initialStep?;
     /** Harness-wide tool pool merged into every context's `unifiedTools`. */
     private readonly harnessTools;
-    /** @internal Memory layers configured for this harness. Exposed non-private
+    /** @internal Context layers configured for this harness. Exposed non-private
      *  so free functions in `runtime/durable/` (checkpoint/restore) can read it
      *  without friend-class gymnastics. Do not access from outside core. */
-    readonly _memory?: MemoryLayer[];
+    readonly _contextLayers?: ContextLayer[];
     private readonly client?;
     private readonly channelStore;
     private readonly callModelOverride?;
@@ -175,7 +191,7 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
     private getOrCreateSession;
     private requireSession;
     callModel(request: CallModelRequest): Promise<LLMResponse>;
-    run<I, O>(s: Step<ContextMemory, I, O>, input: I, ctx: Context): Promise<O>;
+    run<I, O>(s: Step<ContextData, I, O>, input: I, ctx: Context): Promise<O>;
     /** Run all layer `init` hooks before the first step executes. Per spec 11,
      *  init MUST complete before any recall fires so layer state is populated. */
     private initAndRun;
@@ -187,14 +203,16 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
      * clobber accumulated in-memory state.
      */
     private ensureLayersInit;
-    detachedSpawn<I, O>(s: Step<ContextMemory, I, O>, input: I, parentCtx: Context, overrides?: DetachedSpawnOverrides): DetachedHandle<O>;
+    detachedSpawn<I, O>(s: Step<ContextData, I, O>, input: I, parentCtx: Context, overrides?: DetachedSpawnOverrides): DetachedHandle<O>;
     createContext(opts?: {
         parent?: Context;
         items?: Item[];
         state?: unknown;
         threadId?: string;
         resourceId?: string;
-        memory?: MemoryLayer[];
+        context?: ContextLayer[];
+        /** @deprecated Renamed to `context`. */
+        memory?: ContextLayer[];
         /**
          * Initial cwd for the new context. When set, takes precedence over both
          * the parent snapshot and the harness root cwd — used by worktree
@@ -212,15 +230,15 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
     /** Resolves layer-provided tools and merges with step tools into ctx.unifiedTools. */
     private setUnifiedTools;
     private toExecCtx;
-    initLayers(layers: MemoryLayer[], ctx: Context, storage: StorageAdapter): Promise<void>;
-    recallLayers(layers: MemoryLayer[], input: string, ctx: Context): Promise<RecallLayerOutput[]>;
+    initLayers(layers: ContextLayer[], ctx: Context, storage: StorageAdapter): Promise<void>;
+    recallLayers(layers: ContextLayer[], input: string, ctx: Context): Promise<RecallLayerOutput[]>;
     /** Allocate per-layer recall budgets from the harness projection policy. */
     private layerBudgets;
-    recallLayersAtomic(layers: MemoryLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<RecallLayerOutput[]>;
-    recallLayersEventual(layers: MemoryLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<RecallLayerOutput[]>;
+    recallLayersAtomic(layers: ContextLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<RecallLayerOutput[]>;
+    recallLayersEventual(layers: ContextLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<RecallLayerOutput[]>;
     /**
      * Compute the items array that would be sent to the model on the next turn —
-     * the same arrangement `executeLLM` builds: harness-level memory layers'
+     * the same arrangement `executeLLM` builds: harness-level context layers'
      * recall outputs concatenated with the session's accumulated history.
      *
      * Read-mostly: `recallLayers` writes layer-state snapshots to
@@ -228,8 +246,8 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
      * remain consistent with what the next real turn produces.
      */
     previewRequestItems(scope?: SessionScope): Promise<ReadonlyArray<Item>>;
-    storeLayers(layers: MemoryLayer[], response: LLMResponse, ctx: Context): Promise<void>;
-    disposeLayers(layers: MemoryLayer[], ctx: Context): Promise<void>;
+    storeLayers(layers: ContextLayer[], response: LLMResponse, ctx: Context): Promise<void>;
+    disposeLayers(layers: ContextLayer[], ctx: Context): Promise<void>;
     /**
      * Snapshot the execution state at a checkpoint boundary.
      *
@@ -258,7 +276,7 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
      * checkpoint via `CheckpointStore.clear()` and start a fresh execution.
      *
      * `opts` is the `createContext`-shaped wiring the host attached to the
-     * original context (broadcaster, parent, state, memory overrides). A
+     * original context (broadcaster, parent, state, context overrides). A
      * snapshot recovers data, not live objects — pass the same wiring here or
      * the resumed run gets an undecorated context and whatever depended on that
      * wiring (event streaming, mid-turn injection) stops working without
@@ -270,14 +288,53 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
      * whose `id` is already the original `executionId`.
      */
     restore(executionId: string, opts?: RestoreCheckpointOptions): Promise<Context | null>;
-    cancel(_ctx: Context, _reason?: string): Promise<void>;
+    /**
+     * Discard everything `restore(executionId)` would have used — the snapshot *and* the
+     * step-completion ledger — so the next run of that execution starts clean.
+     *
+     * Hosts must call this rather than resume when the workflow itself changed. A resumed
+     * run replays at the coarsest completed granularity: a parent step that finished
+     * replays wholesale, so an edit to one of its children is never noticed and the stale
+     * output wins. Divergence detection only catches a changed step *at* a recorded path.
+     *
+     * Also the right call after a terminal outcome (the execution finished, or the user
+     * abandoned it) — `CheckpointStore.clear` alone leaves the ledger's per-step keys
+     * behind, and nothing else enumerates them.
+     */
+    clearCheckpoint(executionId: string): Promise<void>;
+    /**
+     * Cancel an execution: abort `ctx` and every live descendant context, then
+     * run the context-layer teardown for each (spec 09, Cancellation).
+     *
+     * The abort itself fans out top-down and synchronously — `ctx.abort()`
+     * cascades into every live fork path and spawn child, so no corner of the
+     * tree keeps working while cleanup is in progress. Cleanup then runs
+     * bottom-up: a child's `onComplete` / `dispose` fires before its parent's.
+     *
+     * Aborting a context rejects everything blocked on it (channel `recv`
+     * waiters, parked senders) with `{ kind: 'cancelled' }`, stops its in-flight
+     * model call and sub-harness turn, and makes the next step boundary throw
+     * `cancelled`.
+     *
+     * Cancellation is cooperative: a layer hook already in flight is allowed to
+     * settle, and step code that ignores `ctx.aborted` between `await`s runs to
+     * its next boundary. Calling `cancel()` on an already-cancelled context is a
+     * no-op.
+     */
+    cancel(ctx: Context, reason?: string): Promise<void>;
+    /**
+     * Run the layer lifecycle's abort path for one cancelled context:
+     * `onComplete` with `outcome: 'aborted'`, then `dispose`. Both always run
+     * under cancellation (spec 09, Cancellation item 5).
+     */
+    private teardownCancelledContext;
     createSpan(name: string, parent: Span | null): Span;
     getLayerState<T>(executionId: string, layerId: string): T | undefined;
     setLayerState<T>(executionId: string, layerId: string, state: T): void;
-    beforeToolCall(layers: MemoryLayer[], toolName: string, toolArgs: unknown, ctx: Context): Promise<SteeringDecision>;
-    afterModelCall(layers: MemoryLayer[], response: LLMResponse, ctx: Context): Promise<SteeringDecision>;
-    projectHistory(layers: MemoryLayer[], items: ReadonlyArray<Item>, ctx: Context): Promise<ReadonlyArray<Item>>;
-    runAppendPipeline(layers: MemoryLayer[], items: Item[], ctx: Context): Promise<{
+    beforeToolCall(layers: ContextLayer[], toolName: string, toolArgs: unknown, ctx: Context): Promise<SteeringDecision>;
+    afterModelCall(layers: ContextLayer[], response: LLMResponse, ctx: Context): Promise<SteeringDecision>;
+    projectHistory(layers: ContextLayer[], items: ReadonlyArray<Item>, ctx: Context): Promise<ReadonlyArray<Item>>;
+    runAppendPipeline(layers: ContextLayer[], items: Item[], ctx: Context): Promise<{
         items: Item[];
         rerenderRequests: {
             layerId: string;
@@ -291,7 +348,7 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
         slot: number;
         timing: 'immediate' | 'batched';
         scope: 'self' | 'slot-after' | 'all';
-    }[], layers: MemoryLayer[], ctx: Context, budgets: Map<string, number>, query?: string): Promise<{
+    }[], layers: ContextLayer[], ctx: Context, budgets: Map<string, number>, query?: string): Promise<{
         layerId: string;
         items: Item[];
         tokenCount: number;

package/dist/harness/agent-harness.js

@@ -2,12 +2,13 @@ import { frameworkCast, ItemSchemaRegistry, NoeticConfigError } from '@noetic-to
 import { SpanImpl } from '../observability/span-impl.js';
 import { NoopExporter } from '../observability/trace-exporter.js';
 import { createInMemoryFsAdapter, createInMemoryShellAdapter, createInMemorySubprocessAdapter, OpenRouter, } from './deps/adapters.js';
+import { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, completeLayers, contextToExecCtx, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from './deps/context.js';
 import { collectAllTools, deduplicateTools, dispatchStepThroughAdapter, execute, } from './deps/interpreter.js';
-import { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, contextToExecCtx, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from './deps/memory.js';
-import { buildItemStream, ChannelStore, ContextImpl, captureCheckpoint, createInMemoryStorage, createStepLedgerStore, filterReasoningStream, filterTextStream, restoreFromCheckpoint, SessionRunner, StepLedger, snapshotCwdState, } from './deps/runtime.js';
+import { buildItemStream, ChannelStore, ContextImpl, captureCheckpoint, clearCheckpoint, collectContextTree, createInMemoryStorage, createStepLedgerStore, filterReasoningStream, filterTextStream, resolveStepLedgerRetention, restoreFromCheckpoint, SessionRunner, StepLedger, snapshotCwdState, } from './deps/runtime.js';
 import { SteeringAction } from './deps/types.js';
 import { AgentHarnessModelCaller } from './model-call.js';
 export { createStreamIdleWatchdog } from './model-call.js';
+import { resolveContextOption } from '../builders/context-option.js';
 import { buildItemSchemaRegistry } from './model-schema.js';
 //#endregion
 const DEFAULT_THREAD_ID = '__default__';
@@ -104,8 +105,8 @@ function createClient(config) {
 }
 //#region AgentHarness
 /**
- * Default agent harness for executing agent steps with built-in channel, memory, and trace support.
- * Provides channel store, memory layer lifecycle, and trace export with no external dependencies.
+ * Default agent harness for executing agent steps with built-in channel, context, and trace support.
+ * Provides channel store, context layer lifecycle, and trace export with no external dependencies.
  *
  * Messages submitted via `execute()` are enqueued on a per-thread session and
  * processed by a `SessionRunner`. Consumers observe responses via the session-
@@ -130,13 +131,19 @@ export class AgentHarness {
      * @internal
      */
     stepLedgerStore;
+    /**
+     * Resolved retention bounds for that ledger. Validated at construction so a bad cap
+     * is a loud config error rather than a run that silently records nothing.
+     * @internal
+     */
+    stepLedgerRetention;
     initialStep;
     /** Harness-wide tool pool merged into every context's `unifiedTools`. */
     harnessTools;
-    /** @internal Memory layers configured for this harness. Exposed non-private
+    /** @internal Context layers configured for this harness. Exposed non-private
      *  so free functions in `runtime/durable/` (checkpoint/restore) can read it
      *  without friend-class gymnastics. Do not access from outside core. */
-    _memory;
+    _contextLayers;
     client;
     channelStore;
     callModelOverride;
@@ -192,9 +199,10 @@ export class AgentHarness {
                 storage: this.config.storage ?? createInMemoryStorage(),
             })
             : undefined;
+        this.stepLedgerRetention = resolveStepLedgerRetention(opts.stepLedgerRetention);
         this.initialStep = opts.initialStep;
         this.harnessTools = opts.tools ?? [];
-        this._memory = opts.memory;
+        this._contextLayers = resolveContextOption(opts);
         this.callModelOverride = opts._testCallModel;
         this.client = opts._testCallModel ? undefined : createClient(opts.llm);
         this.channelStore = new ChannelStore();
@@ -202,7 +210,7 @@ export class AgentHarness {
         this.layerStateStore =
             opts.layerStateStore ??
                 createLayerStateStore((layerId, hook, error) => {
-                    console.warn(`[noetic] memory layer '${layerId}' ${hook} error:`, error);
+                    console.warn(`[noetic] context layer '${layerId}' ${hook} error:`, error);
                 });
         this.recallCache = createRecallCache();
         this.defaultDeliveryMode = opts.defaultDeliveryMode ?? 'next-turn';
@@ -315,7 +323,7 @@ export class AgentHarness {
                 threadId,
                 agentName: this.config.name,
                 // The first queued message in a batch establishes `resourceId` /
-                // `state` / `memory` for the turn. If multiple messages are drained
+                // `state` / `context` for the turn. If multiple messages are drained
                 // together (queue flush), later messages' values for these fields
                 // are ignored. `deliveryMode` is resolved per-message at enqueue
                 // time and doesn't apply here.
@@ -330,7 +338,7 @@ export class AgentHarness {
                         threadId,
                         resourceId: perTurnOptions.resourceId,
                         state: perTurnOptions.state,
-                        memory: perTurnOptions.memory,
+                        context: resolveContextOption(perTurnOptions),
                         _broadcaster: session.runner.broadcaster,
                     });
                     const ext = frameworkCast(ctx);
@@ -412,8 +420,8 @@ export class AgentHarness {
                 ...this.harnessTools,
             ]);
         }
-        // Hydrate/recall/persist memory on the bare `run()` path too (issue #48):
-        // configuring `memory` + `storage` must "just work" without going through
+        // Hydrate/recall/persist context on the bare `run()` path too (issue #48):
+        // configuring `context` + `storage` must "just work" without going through
         // `execute()`/`seedSessionHistory`. Idempotent — see `ensureLayersInit`.
         await this.ensureLayersInit(ctx);
         return execute(s, input, ctx);
@@ -451,11 +459,14 @@ export class AgentHarness {
         return dispatchStepThroughAdapter(this, s, input, parentCtx, overrides);
     }
     createContext(opts) {
-        const { memory: memoryLayers, cwdInit, ...rest } = opts ?? {};
-        const effectiveMemory = memoryLayers ?? this._memory;
+        const resolved = opts ?? {};
+        // `ContextImpl` takes the layers as `layers`, so both option spellings are
+        // dropped from `rest` rather than spread through under the wrong name.
+        const { context: _context, memory: _memory, cwdInit, ...rest } = resolved;
+        const effectiveLayers = resolveContextOption(resolved) ?? this._contextLayers;
         const itemSchemas = buildItemSchemaRegistry({
             base: this.itemSchemas,
-            layers: effectiveMemory,
+            layers: effectiveLayers,
         });
         /* The execution id is chosen here rather than inside ContextImpl so the ledger
          * can be keyed to it — the ledger's storage keys and `ctx.id` must agree for a
@@ -466,7 +477,7 @@ export class AgentHarness {
             id: executionId,
             harness: this,
             channelStore: this.channelStore,
-            layers: effectiveMemory,
+            layers: effectiveLayers,
             itemSchemas,
             cwdState: resolveContextCwdState(this.rootCwdState, opts?.parent, cwdInit),
             // Without this `ctx.checkpoint()` is inert, and the boundaries below never
@@ -476,6 +487,7 @@ export class AgentHarness {
                 ? new StepLedger({
                     executionId,
                     store: this.stepLedgerStore,
+                    retention: this.stepLedgerRetention,
                 })
                 : undefined,
         });
@@ -578,7 +590,7 @@ export class AgentHarness {
     }
     /**
      * Compute the items array that would be sent to the model on the next turn —
-     * the same arrangement `executeLLM` builds: harness-level memory layers'
+     * the same arrangement `executeLLM` builds: harness-level context layers'
      * recall outputs concatenated with the session's accumulated history.
      *
      * Read-mostly: `recallLayers` writes layer-state snapshots to
@@ -598,7 +610,7 @@ export class AgentHarness {
         const ctx = this.createContext({
             items: historyItems,
             threadId,
-            memory: this._memory,
+            context: this._contextLayers,
         });
         const layers = ctx.layers ?? [];
         if (layers.length === 0) {
@@ -671,7 +683,7 @@ export class AgentHarness {
      * checkpoint via `CheckpointStore.clear()` and start a fresh execution.
      *
      * `opts` is the `createContext`-shaped wiring the host attached to the
-     * original context (broadcaster, parent, state, memory overrides). A
+     * original context (broadcaster, parent, state, context overrides). A
      * snapshot recovers data, not live objects — pass the same wiring here or
      * the resumed run gets an undecorated context and whatever depended on that
      * wiring (event streaming, mid-turn injection) stops working without
@@ -685,8 +697,77 @@ export class AgentHarness {
     async restore(executionId, opts) {
         return restoreFromCheckpoint(this, executionId, opts);
     }
+    /**
+     * Discard everything `restore(executionId)` would have used — the snapshot *and* the
+     * step-completion ledger — so the next run of that execution starts clean.
+     *
+     * Hosts must call this rather than resume when the workflow itself changed. A resumed
+     * run replays at the coarsest completed granularity: a parent step that finished
+     * replays wholesale, so an edit to one of its children is never noticed and the stale
+     * output wins. Divergence detection only catches a changed step *at* a recorded path.
+     *
+     * Also the right call after a terminal outcome (the execution finished, or the user
+     * abandoned it) — `CheckpointStore.clear` alone leaves the ledger's per-step keys
+     * behind, and nothing else enumerates them.
+     */
+    async clearCheckpoint(executionId) {
+        return clearCheckpoint(this, executionId);
+    }
     //#endregion
-    async cancel(_ctx, _reason) { }
+    /**
+     * Cancel an execution: abort `ctx` and every live descendant context, then
+     * run the context-layer teardown for each (spec 09, Cancellation).
+     *
+     * The abort itself fans out top-down and synchronously — `ctx.abort()`
+     * cascades into every live fork path and spawn child, so no corner of the
+     * tree keeps working while cleanup is in progress. Cleanup then runs
+     * bottom-up: a child's `onComplete` / `dispose` fires before its parent's.
+     *
+     * Aborting a context rejects everything blocked on it (channel `recv`
+     * waiters, parked senders) with `{ kind: 'cancelled' }`, stops its in-flight
+     * model call and sub-harness turn, and makes the next step boundary throw
+     * `cancelled`.
+     *
+     * Cancellation is cooperative: a layer hook already in flight is allowed to
+     * settle, and step code that ignores `ctx.aborted` between `await`s runs to
+     * its next boundary. Calling `cancel()` on an already-cancelled context is a
+     * no-op.
+     */
+    async cancel(ctx, reason) {
+        if (ctx.aborted) {
+            return;
+        }
+        // Snapshot the tree first: `abort()` cascades and clears each context's
+        // child registry, so collecting afterwards would find nothing.
+        const tree = collectContextTree(ctx);
+        ctx.abort(reason);
+        for (const node of tree.reverse()) {
+            await this.teardownCancelledContext(node);
+        }
+    }
+    /**
+     * Run the layer lifecycle's abort path for one cancelled context:
+     * `onComplete` with `outcome: 'aborted'`, then `dispose`. Both always run
+     * under cancellation (spec 09, Cancellation item 5).
+     */
+    async teardownCancelledContext(ctx) {
+        const layers = ctx.layers ?? [];
+        if (layers.length === 0) {
+            return;
+        }
+        await completeLayers({
+            layers: [
+                ...layers,
+            ],
+            ctx: this.toExecCtx(ctx),
+            log: ctx.itemLog,
+            outcome: 'aborted',
+            store: this.layerStateStore,
+        });
+        await this.disposeLayers([
+            ...layers,
+        ], ctx);
+    }
     createSpan(name, parent) {
         return new SpanImpl(name, parent);
     }

package/dist/harness/deps/context.d.ts

@@ -0,0 +1,2 @@
+export type { LayerStateStore, RecallCache } from '@noetic-tools/context';
+export { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, completeLayers, contextToExecCtx, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from '@noetic-tools/context';

package/dist/harness/deps/context.js

@@ -0,0 +1 @@
+export { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, completeLayers, contextToExecCtx, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from '@noetic-tools/context';

package/dist/harness/deps/runtime.d.ts

@@ -1,11 +1,11 @@
 export { ChannelStore } from '../../runtime/channel-store.js';
-export { ContextImpl } from '../../runtime/context-impl.js';
+export { ContextImpl, collectContextTree } from '../../runtime/context-impl.js';
 export { snapshotCwdState } from '../../runtime/cwd-helpers.js';
 export type { CheckpointStore } from '../../runtime/durable/index.js';
 export type { RestoreCheckpointOptions } from '../../runtime/durable/harness-checkpoints.js';
-export { captureCheckpoint, restoreFromCheckpoint, } from '../../runtime/durable/harness-checkpoints.js';
-export type { StepLedgerEntry, StepLedgerStore } from '../../runtime/durable/step-ledger.js';
-export { createStepLedgerStore, StepLedger } from '../../runtime/durable/step-ledger.js';
+export { captureCheckpoint, clearCheckpoint, restoreFromCheckpoint, } from '../../runtime/durable/harness-checkpoints.js';
+export type { StepLedgerEntry, StepLedgerRetention, StepLedgerStore, } from '../../runtime/durable/step-ledger.js';
+export { createStepLedgerStore, resolveStepLedgerRetention, StepLedger, } from '../../runtime/durable/step-ledger.js';
 export type { EventBroadcaster } from '../../runtime/event-broadcaster.js';
 export { createInMemoryStorage } from '../../runtime/in-memory-storage.js';
 export type { QueuedMessage } from '../../runtime/message-queue.js';

package/dist/harness/deps/runtime.js

@@ -1,8 +1,8 @@
 export { ChannelStore } from '../../runtime/channel-store.js';
-export { ContextImpl } from '../../runtime/context-impl.js';
+export { ContextImpl, collectContextTree } from '../../runtime/context-impl.js';
 export { snapshotCwdState } from '../../runtime/cwd-helpers.js';
-export { captureCheckpoint, restoreFromCheckpoint, } from '../../runtime/durable/harness-checkpoints.js';
-export { createStepLedgerStore, StepLedger } from '../../runtime/durable/step-ledger.js';
+export { captureCheckpoint, clearCheckpoint, restoreFromCheckpoint, } from '../../runtime/durable/harness-checkpoints.js';
+export { createStepLedgerStore, resolveStepLedgerRetention, StepLedger, } from '../../runtime/durable/step-ledger.js';
 export { createInMemoryStorage } from '../../runtime/in-memory-storage.js';
 export { SessionRunner } from '../../runtime/session-runner.js';
 export { buildItemStream, filterReasoningStream, filterTextStream, } from '../../runtime/session-streams.js';

package/dist/harness/deps/types.d.ts

@@ -1,4 +1,4 @@
-export type { ContextMemory, ExecutionContext, MemoryLayer, ProjectionPolicy, StorageAdapter, } from '@noetic-tools/memory';
+export type { ContextData, ContextLayer, ExecutionContext, ProjectionPolicy, StorageAdapter, } from '@noetic-tools/context';
 export type { AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, Channel, ChannelHandle, Context, CwdState, DeliveryMode, DetachedHandle, ExecuteInput, ExecuteOptions, ExternalChannel, FsAdapter, HarnessResponse, HarnessStatus, Item, ItemSchemaExtensions, LLMResponse, LlmProviderConfig, RecallLayerOutput, SessionScope, ShellAdapter, Span, SteeringDecision, Step, StreamEvent, StreamingItem, SubHarnessSession, SubprocessAdapter, Tool, TraceExporter, } from '@noetic-tools/types';
 export { SteeringAction } from '@noetic-tools/types';
 export type { ZodType } from 'zod';

package/dist/harness/model-schema.d.ts

@@ -1,8 +1,8 @@
-import type { MemoryLayer } from '@noetic-tools/memory';
+import type { ContextLayer } from '@noetic-tools/context';
 import type { Item, ItemSchemaRegistry, Tool } from '@noetic-tools/types';
 export declare function buildItemSchemaRegistry({ base, layers, tools, }: {
     base: ItemSchemaRegistry;
-    layers?: ReadonlyArray<MemoryLayer>;
+    layers?: ReadonlyArray<ContextLayer>;
     tools?: ReadonlyArray<Tool>;
 }): ItemSchemaRegistry;
 /**

package/dist/index.d.ts

@@ -9,6 +9,8 @@ export { createOpenRouterEmbed } from './adapters/openrouter.js';
 /** @public */
 export { channel } from './builders/channel-builder.js';
 /** @public */
+export { context } from './builders/context-builder.js';
+/** @public */
 export { branch, fork } from './builders/control-flow-builders.js';
 /** @public */
 export type { EveryOptions } from './builders/every.js';
@@ -21,20 +23,20 @@ export type { LoopConfig } from './builders/loop-builder.js';
 /** @public */
 export { loop } from './builders/loop-builder.js';
 /** @public */
-export { memory } from './builders/memory-builder.js';
-/** @public */
 export { provide } from './builders/provide-builder.js';
 /** @public */
 export { spawn } from './builders/spawn-builder.js';
 /** @public */
-export { step } from './builders/step-builders.js';
-/** @public */
 export { tool, toolWithGenerator } from './builders/tool-builder.js';
 /** @public */
 export type { HydrationContext } from './builders/workflow-hydrator.js';
 /** @public */
 export { hydrateNode, hydrateWorkflow } from './builders/workflow-hydrator.js';
 /** @public */
+export type { StepWorkflowOpts } from './builders/workflow-step.js';
+/** @public */
+export { step } from './builders/workflow-step.js';
+/** @public */
 export type { Condition, OtherwiseClause, WhenClause } from './conditions/conditions.js';
 /** @public */
 export { aiCondition, allCondition, anyCondition, embeddingMatch, otherwise, semanticRoute, semanticSwitch, when, } from './conditions/conditions.js';
@@ -55,7 +57,7 @@ export { execute } from './interpreter/execute.js';
 /** @public */
 /** @public */
 /** @public */
-export type { DurableTaskState, FactExtractor, FactSearcher, HistoryWindowConfig, ObservationalMemoryConfig, ObservationalState, PlanEnterSessionCallback, PlanExecutionEntry, PlanExitCallback, PlanMemoryConfig, PlanState, TemporalFact, TemporalMemoryConfig, TemporalSearchResult, WorkingMemoryConfig, WorkingMemoryState, } from '@noetic-tools/memory';
+export type { DurableTaskState, FactExtractor, FactSearcher, HistoryWindowConfig, ObservationalContextConfig, ObservationalState, PlanContextConfig, PlanEnterSessionCallback, PlanExecutionEntry, PlanExitCallback, PlanState, TemporalContextConfig, TemporalFact, TemporalSearchResult, WorkingMemoryContextConfig, WorkingMemoryContextState, } from '@noetic-tools/context';
 /** @public */
 /** @public */
 /** @public */
@@ -68,7 +70,7 @@ export type { DurableTaskState, FactExtractor, FactSearcher, HistoryWindowConfig
 /** @public */
 /** @public */
 /** @public */
-export { durableTaskState, fileReference, findFunctionCall, historyWindow, observationalMemory, PlanPhase, planMemory, staticContent, steering, storageGetMany, stripUnresolvedToolCalls, temporalMemory, toolMemoryLayer, workingMemory, } from '@noetic-tools/memory';
+export { durableTaskState, fileReference, findFunctionCall, historyWindow, observationalContext, PlanPhase, planContext, staticContent, steering, storageGetMany, stripUnresolvedToolCalls, temporalContext, toolContextLayer, workingMemoryContext, } from '@noetic-tools/context';
 /** @public */
 export { createMessage, estimateTokens } from '@noetic-tools/types';
 /** @public */
@@ -82,10 +84,6 @@ export type { DynamicWorkflowOpts, ParseAndRunWorkflowOpts } from './patterns/dy
 /** @public */
 export { dynamicWorkflow, parseAndRunWorkflow } from './patterns/dynamic-workflow.js';
 /** @public */
-export type { FlowNode, ForkFlowNode, LlmFlowNode, SequenceFlowNode, SpawnFlowNode, SubagentFlowNode, } from './patterns/flow.js';
-/** @public */
-export { FlowSchema, flowDepth, validateFlow, walkFlow } from './patterns/flow.js';
-/** @public */
 export type { InterviewOpts, InterviewQuestionAnswer, InterviewResult } from './patterns/interview.js';
 /** @public */
 export { interview } from './patterns/interview.js';
@@ -100,22 +98,22 @@ export { react } from './patterns/react.js';
 /** @public */
 export { AgentHarness } from './harness/agent-harness.js';
 /** @public */
-export type { AfterFirstTurnContext, CheckpointStore, CreateCheckpointStoreOptions, CreateNudgeMessageOpts, DetachedSignal, RunnableLoopHarness, RunnableLoopOpts, SessionSeedHarness, StallNudgeOpts, } from './runtime/durable/index.js';
+export type { AfterFirstTurnContext, CheckpointStore, CreateCheckpointStoreOptions, CreateNudgeMessageOpts, DetachedSignal, RunnableLoopHarness, RunnableLoopOpts, SessionSeedHarness, StallNudgeOpts, StepLedgerRetention, StepLedgerStats, } from './runtime/durable/index.js';
 /** @public */
-export { CheckpointKeys, createCheckpointStore, createDetachedSignal, createNudgeMessage, createStallNudgeHook, DEFAULT_NUDGE_MESSAGE_TEXT, runnableLoop, seedFromItems, } from './runtime/durable/index.js';
+export { CheckpointKeys, createCheckpointStore, createDetachedSignal, createNudgeMessage, createStallNudgeHook, DEFAULT_NUDGE_MESSAGE_TEXT, DEFAULT_STEP_LEDGER_RETENTION, runnableLoop, seedFromItems, } from './runtime/durable/index.js';
 /** @public */
 export { getRegistry, lookupStep, registerStep } from './runtime/step-registry.js';
 /** @public */
 export { defaultItemSchemaRegistry, ItemSchema, ItemSchemaRegistry } from '@noetic-tools/types';
 /** @public */
-export type { BranchRoute, BranchWorkflowNode, EveryWorkflowNode, ForkWorkflowNode, LlmWorkflowNode, LoopWorkflowNode, MergeStrategy, ProvideWorkflowNode, SequenceWorkflowNode, SpawnWorkflowNode, SubHarnessWorkflowNode, ToolWorkflowNode, UntilPredicate, WorkflowDocument, WorkflowNode, } from './schemas/workflow.js';
+export type { BranchRoute, BranchWorkflowNode, EveryWorkflowNode, ForkWorkflowNode, LlmWorkflowNode, LoopWorkflowNode, MergeStrategy, ProvideWorkflowNode, SequenceWorkflowNode, SpawnWorkflowNode, SubflowWorkflowNode, SubHarnessWorkflowNode, ToolWorkflowNode, UntilPredicate, WorkflowDocument, WorkflowNode, } from './schemas/workflow.js';
 /** @public */
 export { MergeStrategySchema, UntilPredicateSchema, validateWorkflow, WorkflowDocumentSchema, WorkflowNodeSchema, walkWorkflow, workflowDepth, } from './schemas/workflow.js';
 /** @public */
 export type { Channel, ChannelHandle, ExternalChannel } from '@noetic-tools/types';
 /** @public */
 /** @public */
-export type { LLMResponse, LlmProviderConfig, ModelParams, RetryPolicy, ServerToolSpec, StepMeta, TokenUsage, Tool, ToolMemoryDeclaration, } from '@noetic-tools/types';
+export type { LLMResponse, LlmProviderConfig, ModelParams, RetryPolicy, ServerToolSpec, StepMeta, TokenUsage, Tool, ToolContextDeclaration, } from '@noetic-tools/types';
 /** @public */
 export { isServerToolSpec } from '@noetic-tools/types';
 /** @public */
@@ -139,13 +137,13 @@ export type { NoeticError } from '@noetic-tools/types';
 /** @public */
 export type { ContentPart, DeveloperMessageExtensionItem, ExecuteInput, ExtendedItem, ExtensionItem, FileSearchItem, FunctionCallItem, FunctionCallOutputItem, ImageGenerationItem, InferExtendedItem, InputContentPart, InputFilePart, InputImagePart, InputMessageItem, InputTextPart, Item, ItemBase, ItemSchemaExtensions, MessageItem, OutputItem, OutputTextPart, ReasoningItem, ReasoningTextPart, RefusalPart, ServerToolItem, SummaryTextPart, WebSearchItem, } from '@noetic-tools/types';
 /** @public */
-export type { BudgetConfig, CompleteParams, ContextMemory, DisposeParams, InferMemory, InferMemoryShape, InitParams, InitResult, LayerDataDecl, LayerFunctionDecl, LayerProvides, LayerTimeouts, MemoryConfig, MemoryHooks, MemoryLayer, ProjectionPolicy, RecallParams, RecallResult, ReturnParams, ReturnResult, ScopedStorage, SpawnParams, SpawnResult, StorageAdapter, StoreParams, StoreResult, } from '@noetic-tools/memory';
+export type { BudgetConfig, CompleteParams, ContextConfig, ContextData, ContextLayer, ContextLayerHooks, DisposeParams, InferContext, InferContextShape, InitParams, InitResult, LayerDataDecl, LayerFunctionDecl, LayerProvides, LayerTimeouts, ProjectionPolicy, RecallParams, RecallResult, ReturnParams, ReturnResult, ScopedStorage, SpawnParams, SpawnResult, StorageAdapter, StoreParams, StoreResult, } from '@noetic-tools/context';
 /** @public */
-export { Slot } from '@noetic-tools/memory';
+export { Slot } from '@noetic-tools/context';
 /** @public */
-export type { ExecutionContext, ExecutionOutcome, MemoryCallModelRequest, MemoryScope, } from '@noetic-tools/types';
+export type { ContextScope, ExecutionContext, ExecutionOutcome, LayerCallModelRequest, } from '@noetic-tools/types';
 /** @public */
-export type { MemoryTraceSpan, Span, TraceExporter } from '@noetic-tools/types';
+export type { LayerTraceSpan, Span, TraceExporter } from '@noetic-tools/types';
 /** @public */
 export type { FrameworkStreamEvent, HarnessResponse, SdkStreamEvent, StreamEvent, StreamingItem, } from '@noetic-tools/types';
 /** @public */
@@ -170,10 +168,16 @@ export { TIMEOUT_ERROR_PREFIX } from '@noetic-tools/types';
 /** @public Reusable error-serialiser used by custom SubprocessAdapter implementations. */
 export { serializeError } from './adapters/in-memory-subprocess/metadata.js';
 /** @public */
-export type { ToolExecutionContext, ToolMemory } from '@noetic-tools/types';
+export type { ToolContext, ToolExecutionContext } from '@noetic-tools/types';
 /** @public */
 export { all, any } from './until/combinators.js';
 /** @public */
 export type { ConvergeConfig, VerifyFn } from './until/predicates.js';
 /** @public */
 export { until } from './until/predicates.js';
+/**
+ * Pre-rename names for the context layer system — `MemoryLayer`, `memory()`,
+ * `workingMemory`, and friends. Each carries its own `@deprecated` pointer to
+ * its replacement in `./deprecated`. Removed in the next major.
+ */
+export * from './deprecated.js';