@noetic-tools/types 2.0.0 → 2.1.1

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,12 @@ 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 an execution: abort `ctx` and every live descendant context, then
+     * run memory-layer teardown (`onComplete` with `outcome: 'aborted'`, then
+     * `dispose`) bottom-up. A no-op on an already-cancelled context.
+     */
     cancel(ctx: Context, reason?: string): Promise<void>;
     /** Trace exporter spans are flushed to. Defaults to a no-op exporter. */
     readonly traceExporter: TraceExporter;
@@ -216,6 +247,18 @@ export interface Context<TMemory = ContextMemory, TState = unknown> {
     readonly completionValue: unknown;
     readonly aborted: boolean;
     readonly abortReason?: string;
+    /**
+     * Cancel this context and everything running beneath it. The first call wins
+     * (later calls are no-ops, so `abortReason` is stable), and it cascades
+     * *down* the execution tree: every live fork path and spawn child is aborted
+     * too. It never travels up — aborting a child leaves the parent running.
+     *
+     * Aborting rejects operations blocked on the context (channel `recv` waiters,
+     * parked back-pressure senders) with `cancelled`, cuts short the in-flight
+     * model call or sub-harness turn, and makes the next step boundary throw
+     * `cancelled`. Memory-layer teardown is NOT run — use
+     * `harness.cancel(ctx, reason)` for that.
+     */
     abort(reason?: string): void;
 }
 export {};

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,22 @@ 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 an execution. Aborts `ctx` and — cascading down the execution tree —
+     * every live fork path and spawn child, then runs memory-layer teardown
+     * (`onComplete` with `outcome: 'aborted'`, then `dispose`) bottom-up.
+     *
+     * Blocked channel operations reject with `cancelled`, the in-flight model
+     * call and sub-harness turn are cut short, and the next step boundary throws
+     * `cancelled`. Idempotent: cancelling an already-cancelled context is a
+     * no-op. Use `ctx.abort()` when you want the signal without layer teardown.
+     */
     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": "2.0.0",
+  "version": "2.1.1",
   "type": "module",
   "description": "Foundational type contracts and primitives shared across the Noetic framework (items, LLM config, adapters, steering, errors).",
   "license": "Apache-2.0",