@noetic-tools/types 1.4.0 → 2.1.0

package/dist/types/context.d.ts

@@ -61,6 +61,32 @@ export interface ContextDetachedSpawnOverrides {
     resourceId?: string;
     cwdInit?: string;
 }
+/**
+ * @public Caller-supplied wiring forwarded to the `createContext` call that
+ * `harness.restore()` makes internally.
+ *
+ * A snapshot recovers the item log, layer state, cwd, and identity — it cannot
+ * recover the live objects a host attached when it built the original context
+ * (event broadcasters, queues, per-host state). Pass the same wiring here that
+ * was passed to `createContext` originally, or the resumed run silently loses
+ * it.
+ *
+ * Snapshot-owned fields (`items`, `threadId`, `resourceId`, `cwdInit`) are
+ * deliberately absent: they always come from the persisted snapshot, so
+ * accepting them here would only offer a value that gets ignored.
+ *
+ * Anything a host attaches *after* construction — `Object.assign`ed fields,
+ * abort registration — stays the host's responsibility and can be applied to
+ * the context `restore()` returns.
+ */
+export interface RestoreContextOptions {
+    /** Live parent context, when the restored execution hangs under one. */
+    parent?: Context;
+    /** Opaque per-execution state, same as `createContext({ state })`. */
+    state?: unknown;
+    /** Memory layers for the restored context. Defaults to the harness's configured layers. */
+    memory?: MemoryLayer[];
+}
 export interface ContextRerenderRequest {
     layerId: string;
     slot: number;
@@ -150,7 +176,7 @@ export interface ContextHarness {
     initLayers(layers: MemoryLayer[], ctx: Context, storage: StorageAdapter): Promise<void>;
     disposeLayers(layers: MemoryLayer[], ctx: Context): Promise<void>;
     checkpoint(ctx: Context): Promise<void>;
-    restore(executionId: string): Promise<Context | null>;
+    restore(executionId: string, opts?: RestoreContextOptions): Promise<Context | null>;
     cancel(ctx: Context, reason?: string): Promise<void>;
     /** Trace exporter spans are flushed to. Defaults to a no-op exporter. */
     readonly traceExporter: TraceExporter;

package/dist/types/memory.d.ts

@@ -113,6 +113,21 @@ export interface StorageAdapter {
     set<T>(key: string, value: T): Promise<void>;
     delete(key: string): Promise<void>;
     list(prefix: string): Promise<string[]>;
+    /**
+     * Batch read. Anything that lists a prefix and then reads each key is an N+1 —
+     * one round trip per key on a network- or database-backed adapter, which is
+     * exactly what a resume path cannot afford. Implement this and the round trips
+     * collapse to one.
+     *
+     * Optional so existing adapters keep working: callers MUST NOT depend on it
+     * directly — go through `storageGetMany`, which falls back to a parallel
+     * `get` sweep when a backend has not implemented it.
+     *
+     * Keys with no stored value are ABSENT from the returned map. The map is never
+     * sparse-with-nulls, so `map.size < keys.length` is the normal way to see that
+     * something was missing.
+     */
+    getMany?<T>(keys: string[]): Promise<Map<string, T>>;
 }
 /** @public Scope-namespaced storage interface provided to memory layer init hooks. */
 export interface ScopedStorage {
@@ -120,6 +135,13 @@ export interface ScopedStorage {
     set<T>(key: string, value: T): Promise<void>;
     delete(key: string): Promise<void>;
     list(prefix?: string): Promise<string[]>;
+    /**
+     * Batch read, always available — the scoped wrapper supplies the fallback so a
+     * layer never has to check. Returned keys are scope-relative (the namespace
+     * prefix is stripped, as with `list`), and missing keys are absent rather than
+     * null.
+     */
+    getMany<T>(keys: string[]): Promise<Map<string, T>>;
 }
 /** @public Parameters passed to a memory layer's `init` hook. */
 export interface InitParams {

package/dist/types/runtime.d.ts

@@ -1,7 +1,7 @@
 import type { ZodType } from 'zod';
 import type { Channel, ChannelHandle, ExternalChannel } from './channel.js';
 import type { LLMResponse, ModelParams, ServerToolSpec } from './common.js';
-import type { Context, CwdState } from './context.js';
+import type { Context, CwdState, RestoreContextOptions } from './context.js';
 import type { DetachedHandle } from './detached.js';
 import type { FsAdapter } from './fs-adapter.js';
 import type { HarnessResponse, StreamEvent, StreamingItem } from './harness-result.js';
@@ -245,7 +245,12 @@ export interface AgentHarnessContract<TParams extends Record<string, unknown> =
     storeLayers(layers: MemoryLayer[], response: LLMResponse, ctx: Context): Promise<void>;
     disposeLayers(layers: MemoryLayer[], ctx: Context): Promise<void>;
     checkpoint(ctx: Context): Promise<void>;
-    restore(executionId: string): Promise<Context | null>;
+    /**
+     * Rebuild a `Context` from a persisted snapshot. `opts` carries the wiring
+     * the host attached when it created the original context — without it a
+     * decorated context is silently replaced by a bare one on resume.
+     */
+    restore(executionId: string, opts?: RestoreContextOptions): Promise<Context | null>;
     cancel(ctx: Context, reason?: string): Promise<void>;
     /** Trace exporter spans are flushed to. Defaults to a no-op exporter. */
     readonly traceExporter: TraceExporter;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/types",
-  "version": "1.4.0",
+  "version": "2.1.0",
   "type": "module",
   "description": "Foundational type contracts and primitives shared across the Noetic framework (items, LLM config, adapters, steering, errors).",
   "license": "Apache-2.0",