@noetic-tools/core 3.1.0 → 4.0.0

package/dist/runtime/durable/index.d.ts

@@ -8,3 +8,5 @@ export type { SessionSeedHarness } from './session-seed.js';
 export { seedFromItems } from './session-seed.js';
 export type { CreateNudgeMessageOpts, StallNudgeOpts } from './stall-nudge.js';
 export { createNudgeMessage, createStallNudgeHook, DEFAULT_NUDGE_MESSAGE_TEXT, } from './stall-nudge.js';
+export type { StepLedgerRetention, StepLedgerStats } from './step-ledger.js';
+export { DEFAULT_STEP_LEDGER_RETENTION } from './step-ledger.js';

package/dist/runtime/durable/index.js

@@ -3,3 +3,4 @@ export { createDetachedSignal } from './detached-signal.js';
 export { runnableLoop } from './runnable-loop.js';
 export { seedFromItems } from './session-seed.js';
 export { createNudgeMessage, createStallNudgeHook, DEFAULT_NUDGE_MESSAGE_TEXT, } from './stall-nudge.js';
+export { DEFAULT_STEP_LEDGER_RETENTION } from './step-ledger.js';

package/dist/runtime/durable/step-ledger.d.ts

@@ -10,8 +10,14 @@
  * Entries are stored one key per step so appends are O(1). Folding the whole ledger
  * into the single `execution:<id>:snapshot` key would rewrite a growing blob on every
  * step — O(n²) bytes over a run.
+ *
+ * Sharding bounds the cost of one append but not the total, so retention is bounded on
+ * two axes (`StepLedgerRetention`): an oversized entry is dropped rather than written,
+ * and past `maxEntries` the oldest entry is evicted. Both degradations are safe by
+ * construction — a missing entry re-runs its step, which costs work rather than
+ * correctness.
  */
-import type { StorageAdapter } from '@noetic-tools/memory';
+import type { StorageAdapter } from '@noetic-tools/context';
 import { z } from 'zod';
 /** @public One completed step, keyed by its execution path. */
 export declare const StepLedgerEntrySchema: z.ZodObject<{
@@ -23,46 +29,128 @@ export declare const StepLedgerEntrySchema: z.ZodObject<{
 }, z.core.$strip>;
 /** @public A completed step recorded for replay. */
 export type StepLedgerEntry = z.infer<typeof StepLedgerEntrySchema>;
+/**
+ * @public
+ * Bounds on what one execution's ledger retains. Both caps degrade resume rather than
+ * break it: a step with no entry simply runs again, so the worst case is repeated work
+ * (and repeated side effects — see `specs/23a-step-level-resume` § "The side-effect
+ * boundary"), never a replayed value that disagrees with the recorded run.
+ */
+export interface StepLedgerRetention {
+    /**
+     * Largest output, in UTF-8 bytes of its JSON encoding, that will be recorded. A step
+     * whose output exceeds this is not recorded at all and re-runs on resume. Keeps one
+     * entry inside the per-value limit real storage backends impose (128 KiB on several)
+     * instead of failing the write. Pass `Infinity` to record any size.
+     *
+     * Defaults to `DEFAULT_STEP_LEDGER_RETENTION.maxEntryBytes` (128 KiB).
+     */
+    maxEntryBytes?: number;
+    /**
+     * Most entries retained for one execution. Recording past the cap evicts the oldest
+     * entry, so resume is best-effort over a bounded *suffix* of the run: the tail of the
+     * work is skipped, the head runs again. Pass `Infinity` to retain every entry.
+     *
+     * Defaults to `DEFAULT_STEP_LEDGER_RETENTION.maxEntries` (1000).
+     */
+    maxEntries?: number;
+}
+/** @public Retention applied when a harness does not configure `stepLedgerRetention`. */
+export declare const DEFAULT_STEP_LEDGER_RETENTION: {
+    readonly maxEntryBytes: number;
+    readonly maxEntries: 1000;
+};
+/**
+ * @public
+ * Fill in defaults and reject nonsense. Validating loudly matters because every
+ * misconfiguration here fails *silently* at runtime — a negative cap would drop every
+ * entry and the run would look fine while resuming nothing.
+ *
+ * @throws NoeticConfigError `code: 'STEP_LEDGER_RETENTION_INVALID'`
+ */
+export declare function resolveStepLedgerRetention(retention?: StepLedgerRetention): Required<StepLedgerRetention>;
 /** Storage key prefix owning every ledger entry for one execution. */
 export declare function stepLedgerPrefix(executionId: string): string;
+/**
+ * @public
+ * Everything one execution's ledger recovered from storage: the entries available for
+ * replay plus the sequence bookkeeping a further append needs. `nextSeq` cannot be
+ * derived from `entries.size` — retention leaves gaps, and reusing a live sequence
+ * number would overwrite an entry the resumed run still has to replay.
+ */
+export interface StepLedgerWindow {
+    /** Recovered entries, keyed by execution path. Corrupt rows are skipped. */
+    entries: Map<string, StepLedgerEntry>;
+    /** Sequence number the next append takes: highest recorded, plus one. */
+    nextSeq: number;
+    /** Lowest sequence number still in storage — where eviction resumes. */
+    oldestSeq: number;
+}
 /**
  * @public
  * Durable append-only ledger for one harness's executions. Backed by the same
  * `StorageAdapter` as the checkpoint store; it reserves the `:ledger:` suffix that
  * `CheckpointKeys` already sets aside.
+ *
+ * The store owns the key layout only. Retention policy lives in `StepLedger`, which
+ * holds the per-execution sequence cursor that eviction needs.
  */
 export interface StepLedgerStore {
     /** Record a completed step. Sequence numbers order entries within an execution. */
     append: (executionId: string, seq: number, entry: StepLedgerEntry) => Promise<void>;
-    /** Every recorded entry for an execution, keyed by path. Corrupt rows are skipped. */
-    load: (executionId: string) => Promise<Map<string, StepLedgerEntry>>;
+    /** Drop one entry by sequence number. No-op when the key is absent. */
+    delete: (executionId: string, seq: number) => Promise<void>;
+    /** Everything recorded for an execution, plus its sequence bounds. */
+    load: (executionId: string) => Promise<StepLedgerWindow>;
     /** Drop an execution's ledger (paired with `CheckpointStore.clear`). */
     clear: (executionId: string) => Promise<void>;
 }
 export declare function createStepLedgerStore(opts: {
     storage: StorageAdapter;
 }): StepLedgerStore;
+/** @public What retention did to one execution's ledger. Observable for host logging. */
+export interface StepLedgerStats {
+    /** Entries written. */
+    recorded: number;
+    /** Entries not written because their output exceeded `maxEntryBytes`. */
+    droppedOversize: number;
+    /** Entries not written because their output does not survive JSON encoding. */
+    droppedUnserialisable: number;
+    /** Entries deleted to stay within `maxEntries`. */
+    evicted: number;
+}
 /**
  * @public
  * The in-memory ledger a single execution carries: entries recovered from a previous
  * run (available for replay) plus the sequence counter for newly recorded ones.
  *
  * Shared by reference across fork/spawn children so one execution has one ledger —
- * path keys are globally unique across the step tree, so a flat map is correct.
+ * path keys are globally unique across the step tree, so a flat map is correct. That
+ * sharing is also why retention lives here rather than in the store: the sequence
+ * cursor eviction walks belongs to the execution, not to the harness.
  */
 export declare class StepLedger {
     /** Recovered entries, by path. Consumed as replay proceeds. */
     private readonly replayable;
+    /** Sequence number the next recorded entry takes. */
     private seq;
+    /** Lowest sequence number still in storage — advances as eviction proceeds. */
+    private oldestSeq;
     private readonly store?;
     private readonly executionId;
+    private readonly retention;
+    private readonly counts;
     constructor(opts: {
         executionId: string;
         store?: StepLedgerStore;
-        recovered?: Map<string, StepLedgerEntry>;
+        /** What `StepLedgerStore.load` recovered. Absent on a fresh execution. */
+        recovered?: StepLedgerWindow;
+        retention?: StepLedgerRetention;
     });
     /** True when this execution has nothing recovered to replay (the common, fresh case). */
     get isEmpty(): boolean;
+    /** What retention has done so far. A snapshot — safe to hold. */
+    get stats(): StepLedgerStats;
     /**
      * The recorded output for `path`, when a previous run completed the same step there.
      * A divergence (different step id or kind at this path) discards the entry and every
@@ -77,4 +165,18 @@ export declare class StepLedger {
     private discardSubtree;
     /** Record a completed step. Best-effort: a failed write costs resumability, not the run. */
     record(entry: StepLedgerEntry): Promise<void>;
+    /**
+     * Whether this entry is small enough — and encodable at all — to be worth a write.
+     * An output no adapter could serialise is treated exactly like an oversized one:
+     * not recorded, so the step re-runs.
+     */
+    private retainable;
+    /**
+     * Delete oldest-first until the execution is back inside `maxEntries`. The bound is on
+     * the sequence *window* rather than an exact row count, which is what keeps this
+     * correct without a `list()` per append.
+     */
+    private evictOverflow;
+    /** One warning per reason per execution — a long run would otherwise flood the log. */
+    private warnOnFirstDrop;
 }

package/dist/runtime/durable/step-ledger.js

@@ -10,9 +10,17 @@
  * Entries are stored one key per step so appends are O(1). Folding the whole ledger
  * into the single `execution:<id>:snapshot` key would rewrite a growing blob on every
  * step — O(n²) bytes over a run.
+ *
+ * Sharding bounds the cost of one append but not the total, so retention is bounded on
+ * two axes (`StepLedgerRetention`): an oversized entry is dropped rather than written,
+ * and past `maxEntries` the oldest entry is evicted. Both degradations are safe by
+ * construction — a missing entry re-runs its step, which costs work rather than
+ * correctness.
  */
-import { storageGetMany } from '@noetic-tools/memory';
+import { storageGetMany } from '@noetic-tools/context';
+import { NoeticConfigError } from '@noetic-tools/types';
 import { z } from 'zod';
+//#region Entry
 /** @public One completed step, keyed by its execution path. */
 export const StepLedgerEntrySchema = z.object({
     /** Execution path key — see `ContextImpl.currentPath()`. Unique per dispatch. */
@@ -23,6 +31,55 @@ export const StepLedgerEntrySchema = z.object({
     output: z.unknown(),
     completedAt: z.string(),
 });
+/** @public Retention applied when a harness does not configure `stepLedgerRetention`. */
+export const DEFAULT_STEP_LEDGER_RETENTION = {
+    maxEntryBytes: 128 * 1024,
+    maxEntries: 1e3,
+};
+/**
+ * @public
+ * Fill in defaults and reject nonsense. Validating loudly matters because every
+ * misconfiguration here fails *silently* at runtime — a negative cap would drop every
+ * entry and the run would look fine while resuming nothing.
+ *
+ * @throws NoeticConfigError `code: 'STEP_LEDGER_RETENTION_INVALID'`
+ */
+export function resolveStepLedgerRetention(retention) {
+    const resolved = {
+        maxEntryBytes: retention?.maxEntryBytes ?? DEFAULT_STEP_LEDGER_RETENTION.maxEntryBytes,
+        maxEntries: retention?.maxEntries ?? DEFAULT_STEP_LEDGER_RETENTION.maxEntries,
+    };
+    for (const [field, value] of Object.entries(resolved)) {
+        if (value === Number.POSITIVE_INFINITY) {
+            continue;
+        }
+        if (!Number.isFinite(value) || value < 1) {
+            throw new NoeticConfigError({
+                code: 'STEP_LEDGER_RETENTION_INVALID',
+                message: `stepLedgerRetention.${field} must be a positive number or Infinity (received ${String(value)}).`,
+                hint: 'Omit the field to accept the default, or pass Infinity to disable the cap.',
+            });
+        }
+    }
+    return resolved;
+}
+/**
+ * Whether `json` fits `cap` UTF-8 bytes. A UTF-16 code unit encodes to between 1 and 3
+ * UTF-8 bytes (a surrogate pair is 2 units → 4 bytes, i.e. 2 per unit), so string
+ * length brackets the byte count and decides most calls without encoding a megabyte
+ * of output just to measure it.
+ */
+function fitsByteCap(json, cap) {
+    if (json.length > cap) {
+        return false;
+    }
+    if (json.length * 3 <= cap) {
+        return true;
+    }
+    return new TextEncoder().encode(json).length <= cap;
+}
+//#endregion
+//#region Store
 /** Storage key prefix owning every ledger entry for one execution. */
 export function stepLedgerPrefix(executionId) {
     return `execution:${executionId}:ledger:`;
@@ -31,22 +88,43 @@ export function stepLedgerPrefix(executionId) {
 function seqKey(executionId, seq) {
     return `${stepLedgerPrefix(executionId)}${String(seq).padStart(8, '0')}`;
 }
+/** The sequence number a ledger key carries, or null when the suffix is not one. */
+function seqFromKey(executionId, key) {
+    const prefix = stepLedgerPrefix(executionId);
+    if (!key.startsWith(prefix)) {
+        return null;
+    }
+    const seq = Number(key.slice(prefix.length));
+    return Number.isInteger(seq) && seq >= 0 ? seq : null;
+}
 export function createStepLedgerStore(opts) {
     const { storage } = opts;
     return {
         append: async (executionId, seq, entry) => {
             await storage.set(seqKey(executionId, seq), entry);
         },
+        delete: async (executionId, seq) => {
+            await storage.delete(seqKey(executionId, seq));
+        },
         load: async (executionId) => {
             const keys = await storage.list(stepLedgerPrefix(executionId));
             /* One batch read, not one round trip per completed step. Recovery is the
              * moment a network-backed adapter can least afford an N+1. */
-            const entries = await storageGetMany(storage, keys);
-            const byPath = new Map();
+            const raws = await storageGetMany(storage, keys);
+            const entries = new Map();
+            /* Sequence bounds come from the KEYS, not the parsed rows: a row that fails to
+             * parse still occupies its key, so it must not be handed back out as reusable. */
+            let highestSeq = -1;
+            let oldestSeq = -1;
             // Walk `keys`, not the map: `seqKey`'s zero-padding makes `list()` order
             // dispatch order, and a later entry at a path must win over an earlier one.
             for (const key of keys) {
-                const raw = entries.get(key);
+                const seq = seqFromKey(executionId, key);
+                if (seq !== null) {
+                    highestSeq = Math.max(highestSeq, seq);
+                    oldestSeq = oldestSeq === -1 ? seq : Math.min(oldestSeq, seq);
+                }
+                const raw = raws.get(key);
                 if (raw === undefined) {
                     continue;
                 }
@@ -57,9 +135,13 @@ export function createStepLedgerStore(opts) {
                     console.warn(`StepLedger: discarding unreadable entry "${key}": ${parsed.error.message}`);
                     continue;
                 }
-                byPath.set(parsed.data.path, parsed.data);
+                entries.set(parsed.data.path, parsed.data);
             }
-            return byPath;
+            return {
+                entries,
+                nextSeq: highestSeq + 1,
+                oldestSeq: oldestSeq === -1 ? 0 : oldestSeq,
+            };
         },
         clear: async (executionId) => {
             const keys = await storage.list(stepLedgerPrefix(executionId));
@@ -75,24 +157,44 @@ export function createStepLedgerStore(opts) {
  * run (available for replay) plus the sequence counter for newly recorded ones.
  *
  * Shared by reference across fork/spawn children so one execution has one ledger —
- * path keys are globally unique across the step tree, so a flat map is correct.
+ * path keys are globally unique across the step tree, so a flat map is correct. That
+ * sharing is also why retention lives here rather than in the store: the sequence
+ * cursor eviction walks belongs to the execution, not to the harness.
  */
 export class StepLedger {
     /** Recovered entries, by path. Consumed as replay proceeds. */
     replayable;
+    /** Sequence number the next recorded entry takes. */
     seq;
+    /** Lowest sequence number still in storage — advances as eviction proceeds. */
+    oldestSeq;
     store;
     executionId;
+    retention;
+    counts = {
+        recorded: 0,
+        droppedOversize: 0,
+        droppedUnserialisable: 0,
+        evicted: 0,
+    };
     constructor(opts) {
         this.executionId = opts.executionId;
         this.store = opts.store;
-        this.replayable = opts.recovered ?? new Map();
-        this.seq = this.replayable.size;
+        this.retention = resolveStepLedgerRetention(opts.retention);
+        this.replayable = opts.recovered?.entries ?? new Map();
+        this.seq = opts.recovered?.nextSeq ?? 0;
+        this.oldestSeq = opts.recovered?.oldestSeq ?? 0;
     }
     /** True when this execution has nothing recovered to replay (the common, fresh case). */
     get isEmpty() {
         return this.replayable.size === 0;
     }
+    /** What retention has done so far. A snapshot — safe to hold. */
+    get stats() {
+        return {
+            ...this.counts,
+        };
+    }
     /**
      * The recorded output for `path`, when a previous run completed the same step there.
      * A divergence (different step id or kind at this path) discards the entry and every
@@ -125,13 +227,80 @@ export class StepLedger {
         if (!this.store) {
             return;
         }
+        if (!this.retainable(entry)) {
+            return;
+        }
+        /* Reserve the sequence number BEFORE awaiting: concurrent fork legs record through
+         * the one shared ledger, and two of them reading the same counter would write the
+         * same key, silently overwriting a sibling's entry. A write that then fails leaves a
+         * gap, which only makes the window below a slight over-estimate of the live count —
+         * eviction runs marginally early, never late. */
         const seq = this.seq;
-        this.seq += 1;
+        this.seq = seq + 1;
         try {
             await this.store.append(this.executionId, seq, entry);
         }
         catch (error) {
             console.warn(`StepLedger: failed to record "${entry.path}":`, error instanceof Error ? error.message : String(error));
+            return;
+        }
+        this.counts.recorded += 1;
+        await this.evictOverflow();
+    }
+    /**
+     * Whether this entry is small enough — and encodable at all — to be worth a write.
+     * An output no adapter could serialise is treated exactly like an oversized one:
+     * not recorded, so the step re-runs.
+     */
+    retainable(entry) {
+        let json;
+        try {
+            json = JSON.stringify(entry.output);
+        }
+        catch {
+            this.counts.droppedUnserialisable += 1;
+            this.warnOnFirstDrop(this.counts.droppedUnserialisable, `StepLedger: not recording "${entry.path}" — its output does not survive JSON encoding.`);
+            return false;
+        }
+        // `undefined` stringifies to nothing; there is no size to bound.
+        if (json !== undefined && !fitsByteCap(json, this.retention.maxEntryBytes)) {
+            this.counts.droppedOversize += 1;
+            this.warnOnFirstDrop(this.counts.droppedOversize, `StepLedger: not recording "${entry.path}" — output exceeds maxEntryBytes (${this.retention.maxEntryBytes}).`);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Delete oldest-first until the execution is back inside `maxEntries`. The bound is on
+     * the sequence *window* rather than an exact row count, which is what keeps this
+     * correct without a `list()` per append.
+     */
+    async evictOverflow() {
+        const store = this.store;
+        if (!store) {
+            return;
+        }
+        while (this.seq - this.oldestSeq > this.retention.maxEntries) {
+            const victim = this.oldestSeq;
+            try {
+                await store.delete(this.executionId, victim);
+            }
+            catch (error) {
+                /* Leave the cursor where it is and stop: the next append retries this victim
+                 * rather than spinning on a store that is currently refusing deletes. */
+                console.warn(`StepLedger: failed to evict entry ${victim} of "${this.executionId}":`, error instanceof Error ? error.message : String(error));
+                return;
+            }
+            this.oldestSeq = victim + 1;
+            this.counts.evicted += 1;
+        }
+    }
+    /** One warning per reason per execution — a long run would otherwise flood the log. */
+    warnOnFirstDrop(count, message) {
+        if (count > 1) {
+            return;
         }
+        console.warn(`${message} The step will re-run on resume; further drops are silent.`);
     }
 }
+//#endregion

package/dist/runtime/in-memory-storage.d.ts

@@ -1,4 +1,4 @@
-import type { StorageAdapter } from '@noetic-tools/memory';
+import type { StorageAdapter } from '@noetic-tools/context';
 /**
  * @public Process-local, Map-backed StorageAdapter.
  *

package/dist/runtime/session-runner.d.ts

@@ -16,7 +16,7 @@ export interface TurnContext {
  *  (so the runner is the single point of ExecuteInput → Item[] conversion),
  *  plus the messages being delivered this turn so the harness can honour
  *  per-turn `ExecuteOptions` (the first message's options establish
- *  resourceId/state/memory for the turn). */
+ *  resourceId/state/context for the turn). */
 export type CreateContextFn = (items: ReadonlyArray<Item>, turnId: string, messages: ReadonlyArray<QueuedMessage>) => Context;
 export interface SessionRunnerOpts {
     readonly threadId: string;

package/dist/runtime/step-registry.d.ts

@@ -1,10 +1,10 @@
-import type { ContextMemory } from '@noetic-tools/memory';
+import type { ContextData } from '@noetic-tools/context';
 import type { Step } from '@noetic-tools/types';
 /** Registry-wide step type — stored at the widest generic parameters so
  *  callers can register steps with narrower input/output types without
  *  fighting variance. The public `Step` default already uses `unknown` for
  *  the input and output parameters, matching this shape. */
-type RegisteredStep = Step<ContextMemory, unknown, unknown>;
+type RegisteredStep = Step<ContextData, unknown, unknown>;
 /**
  * @public
  * Registers a step so the subprocess adapter can look it up by id.
@@ -18,7 +18,7 @@ type RegisteredStep = Step<ContextMemory, unknown, unknown>;
  * `clearRegistry` wiring is deferred — see the tracked follow-up task on
  * the team's board (strict-registry-plus-test-clear).
  */
-export declare function registerStep<TMemory, I, O>(step: Step<TMemory, I, O>): void;
+export declare function registerStep<TContext, I, O>(step: Step<TContext, I, O>): void;
 /**
  * @public
  * Looks up a registered step by id. Returns `null` when the id is not known

package/dist/runtime/{tool-memory.d.ts → tool-context.d.ts}

@@ -1,4 +1,3 @@
-import type { AgentHarnessContract, Context, ToolExecutionContext, ToolMemory } from '@noetic-tools/types';
+import type { AgentHarnessContract, Context, ToolExecutionContext } from '@noetic-tools/types';
 import type { TurnContext } from '@openrouter/agent';
-export declare function buildToolMemory(harness: AgentHarnessContract, ctx: Context): ToolMemory;
 export declare function buildToolExecutionContext(ctx: Context, harness: AgentHarnessContract, turnContext?: TurnContext): ToolExecutionContext;

package/dist/runtime/{tool-memory.js → tool-context.js}

@@ -1,4 +1,4 @@
-export function buildToolMemory(harness, ctx) {
+function buildToolContext(harness, ctx) {
     return {
         get(layerId) {
             return harness.getLayerState(ctx.id, layerId);
@@ -9,12 +9,15 @@ export function buildToolMemory(harness, ctx) {
     };
 }
 export function buildToolExecutionContext(ctx, harness, turnContext) {
+    const toolContext = buildToolContext(harness, ctx);
     return {
         ctx,
         harness,
         fs: harness.fs,
         shell: harness.shell,
-        memory: buildToolMemory(harness, ctx),
+        context: toolContext,
+        // Deprecated alias — same accessor object, not a copy.
+        memory: toolContext,
         assembledView: ctx.itemLog.items,
         lastStepMeta: ctx.lastStepMeta,
         turnContext,

package/dist/runtime/tool-ui.d.ts

@@ -5,7 +5,7 @@
  * render functions at the call / progress / result / error lifecycle points and
  * forwards each returned `UiFragment` as an `openui.fragment` framework event
  * (namespaced `${agentName}:openui.fragment`). The framework never interprets
- * the fragment source — a UI surface (memory layer + transport) composes it.
+ * the fragment source — a UI surface (context layer + transport) composes it.
  *
  * The `ui` methods are declared bivariantly on `ToolUiDeclaration`, so the
  * erased `Tool` handle the runtime holds can call them with runtime values.

package/dist/runtime/tool-ui.js

@@ -5,7 +5,7 @@
  * render functions at the call / progress / result / error lifecycle points and
  * forwards each returned `UiFragment` as an `openui.fragment` framework event
  * (namespaced `${agentName}:openui.fragment`). The framework never interprets
- * the fragment source — a UI surface (memory layer + transport) composes it.
+ * the fragment source — a UI surface (context layer + transport) composes it.
  *
  * The `ui` methods are declared bivariantly on `ToolUiDeclaration`, so the
  * erased `Tool` handle the runtime holds can call them with runtime values.