@noetic-tools/core 2.5.0 → 3.1.0

package/dist/conditions/conditions.js

@@ -1,3 +1,4 @@
+import { storageGetMany } from '@noetic-tools/memory';
 import { createMessage, extractAssistantText, trackUsage } from '@noetic-tools/types';
 import { z } from 'zod';
 import { cosineSimilarity } from './cosine-similarity.js';
@@ -13,10 +14,12 @@ async function getLabelVectors(embed, labels, ref) {
     if (ref.storage) {
         const storage = ref.storage;
         const keys = labels.map(hashLabel);
-        const fetched = await Promise.all(keys.map((k) => storage.get(k)));
+        // One batch read where the adapter supports it, a parallel `get` sweep where
+        // it does not — either way, not one round trip per label.
+        const cached = await storageGetMany(storage, keys);
         const missingIndices = [];
-        for (let i = 0; i < fetched.length; i++) {
-            if (!fetched[i]) {
+        for (let i = 0; i < keys.length; i++) {
+            if (!cached.has(keys[i])) {
                 missingIndices.push(i);
             }
         }
@@ -29,8 +32,8 @@ async function getLabelVectors(embed, labels, ref) {
         }
         const results = new Array(labels.length);
         let freshIndex = 0;
-        for (let i = 0; i < fetched.length; i++) {
-            results[i] = fetched[i] ?? freshEmbeddings[freshIndex++];
+        for (let i = 0; i < keys.length; i++) {
+            results[i] = cached.get(keys[i]) ?? freshEmbeddings[freshIndex++];
         }
         return results;
     }

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

@@ -1,7 +1,7 @@
 import { ItemSchemaRegistry } from '@noetic-tools/types';
 import type { DetachedSpawnOverrides } from './deps/interpreter.js';
 import type { LayerStateStore, RecallCache } from './deps/memory.js';
-import type { CheckpointStore, EventBroadcaster, StepLedgerStore } from './deps/runtime.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';
 export { createStreamIdleWatchdog } from './model-call.js';
 interface AgentHarnessOpts<TParams extends Record<string, unknown> = Record<string, unknown>> {
@@ -256,8 +256,20 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
      * `NoeticConfigError(CHECKPOINT_SCHEMA_MISMATCH)` when the snapshot's
      * schema version is unrecognised — the caller is expected to discard the
      * 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
+     * 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
+     * failing. Fields the snapshot owns — items, threadId, resourceId, cwd —
+     * are not accepted; they always come from the persisted record.
+     *
+     * Decoration applied *after* construction (`Object.assign`ed fields, abort
+     * registration) stays the host's job: apply it to the context this returns,
+     * whose `id` is already the original `executionId`.
      */
-    restore(executionId: string): Promise<Context | null>;
+    restore(executionId: string, opts?: RestoreCheckpointOptions): Promise<Context | null>;
     cancel(_ctx: Context, _reason?: string): Promise<void>;
     createSpan(name: string, parent: Span | null): Span;
     getLayerState<T>(executionId: string, layerId: string): T | undefined;

package/dist/harness/agent-harness.js

@@ -669,9 +669,21 @@ export class AgentHarness {
      * `NoeticConfigError(CHECKPOINT_SCHEMA_MISMATCH)` when the snapshot's
      * schema version is unrecognised — the caller is expected to discard the
      * 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
+     * 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
+     * failing. Fields the snapshot owns — items, threadId, resourceId, cwd —
+     * are not accepted; they always come from the persisted record.
+     *
+     * Decoration applied *after* construction (`Object.assign`ed fields, abort
+     * registration) stays the host's job: apply it to the context this returns,
+     * whose `id` is already the original `executionId`.
      */
-    async restore(executionId) {
-        return restoreFromCheckpoint(this, executionId);
+    async restore(executionId, opts) {
+        return restoreFromCheckpoint(this, executionId, opts);
     }
     //#endregion
     async cancel(_ctx, _reason) { }

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

@@ -2,6 +2,7 @@ export { ChannelStore } from '../../runtime/channel-store.js';
 export { ContextImpl } 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';

package/dist/index.d.ts

@@ -68,7 +68,7 @@ export type { DurableTaskState, FactExtractor, FactSearcher, HistoryWindowConfig
 /** @public */
 /** @public */
 /** @public */
-export { durableTaskState, fileReference, findFunctionCall, historyWindow, observationalMemory, PlanPhase, planMemory, staticContent, steering, stripUnresolvedToolCalls, temporalMemory, toolMemoryLayer, workingMemory, } from '@noetic-tools/memory';
+export { durableTaskState, fileReference, findFunctionCall, historyWindow, observationalMemory, PlanPhase, planMemory, staticContent, steering, storageGetMany, stripUnresolvedToolCalls, temporalMemory, toolMemoryLayer, workingMemory, } from '@noetic-tools/memory';
 /** @public */
 export { createMessage, estimateTokens } from '@noetic-tools/types';
 /** @public */
@@ -121,7 +121,7 @@ export { isServerToolSpec } from '@noetic-tools/types';
 /** @public */
 /** @public */
 /** @public */
-export type { Context, ContextHarness, CwdState, ItemLog, LastLayerUsage, LayerUsageEntry, } from '@noetic-tools/types';
+export type { Context, ContextHarness, CwdState, ItemLog, LastLayerUsage, LayerUsageEntry, RestoreContextOptions, } from '@noetic-tools/types';
 /** @public */
 export { getToolCwd, setToolCwd, snapshotCwdState } from './runtime/cwd-helpers.js';
 /** @public */

package/dist/index.js

@@ -58,7 +58,7 @@ export { execute } from './interpreter/execute.js';
 /** @public */
 /** @public */
 /** @public */
-export { durableTaskState, fileReference, findFunctionCall, historyWindow, observationalMemory, PlanPhase, planMemory, staticContent, steering, stripUnresolvedToolCalls, temporalMemory, toolMemoryLayer, workingMemory, } from '@noetic-tools/memory';
+export { durableTaskState, fileReference, findFunctionCall, historyWindow, observationalMemory, PlanPhase, planMemory, staticContent, steering, storageGetMany, stripUnresolvedToolCalls, temporalMemory, toolMemoryLayer, workingMemory, } from '@noetic-tools/memory';
 //#endregion
 //#region Message Utilities
 /** @public */

package/dist/runtime/durable/harness-checkpoints.d.ts

@@ -1,7 +1,20 @@
 import type { LayerStateStore, MemoryLayer } from '@noetic-tools/memory';
-import type { Context, Item, ItemSchemaRegistry } from '@noetic-tools/types';
+import type { Context, Item, ItemSchemaRegistry, RestoreContextOptions } from '@noetic-tools/types';
+import type { EventBroadcaster } from '../event-broadcaster.js';
 import type { CheckpointStore } from './checkpoint-store.js';
 import type { StepLedgerStore } from './step-ledger.js';
+/**
+ * Host wiring forwarded into the context `restoreFromCheckpoint` builds.
+ * `RestoreContextOptions` covers the portable fields; core widens it with the
+ * internal `_broadcaster` seam so a resumed turn keeps streaming framework UI
+ * events.
+ *
+ * @internal
+ */
+export type RestoreCheckpointOptions = RestoreContextOptions & {
+    /** @internal Event broadcaster the host attached to the original context. */
+    _broadcaster?: EventBroadcaster;
+};
 /**
  * Minimum harness surface `captureCheckpoint` / `restoreFromCheckpoint`
  * require. `AgentHarness` already satisfies this shape via its
@@ -16,12 +29,11 @@ export interface CheckpointHarnessHandle {
     readonly layerStateStore: LayerStateStore;
     readonly itemSchemas: ItemSchemaRegistry;
     readonly _memory?: MemoryLayer[];
-    createContext(opts?: {
+    createContext(opts?: RestoreCheckpointOptions & {
         items?: Item[];
         threadId?: string;
         resourceId?: string;
         cwdInit?: string;
-        memory?: MemoryLayer[];
     }): Context;
 }
 /**
@@ -41,10 +53,18 @@ export declare function captureCheckpoint(h: CheckpointHarnessHandle, ctx: Conte
  * the restored context observes the pre-crash state through
  * `readLayerState` and the memory projectors.
  *
+ * `opts` carries the host's own context wiring (broadcaster, parent, state,
+ * layer overrides) into the rebuilt context. A snapshot cannot round-trip live
+ * objects, so a host that decorated the original context has to hand the same
+ * decoration back here — otherwise the resumed run gets a bare context and
+ * whatever depended on that wiring stops working silently. Snapshot-owned
+ * fields always win: identity, item log, and cwd come from the persisted
+ * record, never from `opts`.
+ *
  * Preserves the original executionId on the returned context via
  * `Object.defineProperty` — adapter correlation across crash/restart
  * requires a stable id.
  *
  * @internal
  */
-export declare function restoreFromCheckpoint(h: CheckpointHarnessHandle, executionId: string): Promise<Context | null>;
+export declare function restoreFromCheckpoint(h: CheckpointHarnessHandle, executionId: string, opts?: RestoreCheckpointOptions): Promise<Context | null>;

package/dist/runtime/durable/harness-checkpoints.js

@@ -65,13 +65,21 @@ export async function captureCheckpoint(h, ctx) {
  * the restored context observes the pre-crash state through
  * `readLayerState` and the memory projectors.
  *
+ * `opts` carries the host's own context wiring (broadcaster, parent, state,
+ * layer overrides) into the rebuilt context. A snapshot cannot round-trip live
+ * objects, so a host that decorated the original context has to hand the same
+ * decoration back here — otherwise the resumed run gets a bare context and
+ * whatever depended on that wiring stops working silently. Snapshot-owned
+ * fields always win: identity, item log, and cwd come from the persisted
+ * record, never from `opts`.
+ *
  * Preserves the original executionId on the returned context via
  * `Object.defineProperty` — adapter correlation across crash/restart
  * requires a stable id.
  *
  * @internal
  */
-export async function restoreFromCheckpoint(h, executionId) {
+export async function restoreFromCheckpoint(h, executionId, opts) {
     const store = h.checkpointStore;
     if (!store) {
         return null;
@@ -85,12 +93,16 @@ export async function restoreFromCheckpoint(h, executionId) {
     }
     const items = h.itemSchemas.parseMany(snapshot.itemLog.items);
     const cwdInit = snapshot.cwd?.current ?? undefined;
+    /* Caller wiring first, snapshot second: a host may legitimately swap the memory
+     * layers or hang the restored execution under a new parent, but it must never be
+     * able to override the identity/history the snapshot is the record of. */
     const ctx = h.createContext({
+        ...opts,
         items,
         threadId: snapshot.threadId,
         resourceId: snapshot.resourceId,
         cwdInit,
-        memory: h._memory,
+        memory: opts?.memory ?? h._memory,
     });
     if (ctx instanceof ContextImpl) {
         Object.defineProperty(ctx, 'id', {

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

@@ -11,6 +11,7 @@
  * into the single `execution:<id>:snapshot` key would rewrite a growing blob on every
  * step — O(n²) bytes over a run.
  */
+import { storageGetMany } from '@noetic-tools/memory';
 import { z } from 'zod';
 /** @public One completed step, keyed by its execution path. */
 export const StepLedgerEntrySchema = z.object({
@@ -38,10 +39,15 @@ export function createStepLedgerStore(opts) {
         },
         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();
+            // 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 = await storage.get(key);
-                if (raw === null || raw === undefined) {
+                const raw = entries.get(key);
+                if (raw === undefined) {
                     continue;
                 }
                 const parsed = StepLedgerEntrySchema.safeParse(raw);

package/dist/runtime/in-memory-storage.js

@@ -28,6 +28,17 @@ export function createInMemoryStorage() {
                 ...store.keys(),
             ].filter((k) => k.startsWith(prefix));
         },
+        async getMany(keys) {
+            const found = new Map();
+            for (const key of keys) {
+                const val = store.get(key);
+                if (val === undefined) {
+                    continue;
+                }
+                found.set(key, frameworkCast(val));
+            }
+            return found;
+        },
     };
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/core",
-  "version": "2.5.0",
+  "version": "3.1.0",
   "type": "module",
   "description": "Step primitives, interpreter, runtime, and memory layer contract for Noetic agents.",
   "license": "Apache-2.0",
@@ -66,8 +66,8 @@
     }
   },
   "dependencies": {
-    "@noetic-tools/memory": "^1.1.0",
-    "@noetic-tools/types": "^1.4.0",
+    "@noetic-tools/memory": "^2.0.0",
+    "@noetic-tools/types": "^2.1.0",
     "@openrouter/agent": "^0.6.0",
     "zod": "^4.0.0"
   },