@noetic-tools/core 3.0.0 → 3.1.0

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

@@ -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/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/package.json

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