@noetic-tools/core 4.0.0 → 5.0.0

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

@@ -136,6 +136,8 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
     readonly _contextLayers?: ContextLayer[];
     private readonly client?;
     private readonly channelStore;
+    /** Re-entrant `run()` depth per root context id — see `executeClosingChannels`. */
+    private readonly rootRunDepth;
     private readonly callModelOverride?;
     private readonly defaultDeliveryMode;
     private readonly streamIdleTimeoutMs;
@@ -195,6 +197,15 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
     /** Run all layer `init` hooks before the first step executes. Per spec 11,
      *  init MUST complete before any recall fires so layer state is populated. */
     private initAndRun;
+    /**
+     * Run `execute`, closing the execution's external channels when the
+     * OUTERMOST run on a root context finishes (spec 06 Lifecycle: handles flip
+     * `closed`, channel streams end). Patterns re-enter `run()` with the same
+     * root context (`ctx.harness.run(step, input, ctx)`), so a depth count —
+     * not the return itself — marks root completion. Child-context runs never
+     * close anything.
+     */
+    private executeClosingChannels;
     /**
      * Idempotently run layer `init` hooks for `ctx` (keyed by `ctx.id`). Init
      * MUST complete before any recall/store fires so init-bearing layers are not
@@ -227,6 +238,7 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
     }): Promise<T>;
     tryRecv<T>(channel: Channel<T>, _ctx: Context): T | null;
     getChannelHandle<T>(channel: ExternalChannel<T>, executionId: string): ChannelHandle<T>;
+    getChannelStream<T>(channel: ExternalChannel<T>, executionId: string): AsyncIterable<T>;
     /** Resolves layer-provided tools and merges with step tools into ctx.unifiedTools. */
     private setUnifiedTools;
     private toExecCtx;

package/dist/harness/agent-harness.js

@@ -146,6 +146,8 @@ export class AgentHarness {
     _contextLayers;
     client;
     channelStore;
+    /** Re-entrant `run()` depth per root context id — see `executeClosingChannels`. */
+    rootRunDepth = new Map();
     callModelOverride;
     defaultDeliveryMode;
     streamIdleTimeoutMs;
@@ -424,13 +426,46 @@ export class AgentHarness {
         // configuring `context` + `storage` must "just work" without going through
         // `execute()`/`seedSessionHistory`. Idempotent — see `ensureLayersInit`.
         await this.ensureLayersInit(ctx);
-        return execute(s, input, ctx);
+        return this.executeClosingChannels(s, input, ctx);
     }
     /** Run all layer `init` hooks before the first step executes. Per spec 11,
      *  init MUST complete before any recall fires so layer state is populated. */
     async initAndRun(s, input, ctx) {
         await this.ensureLayersInit(ctx);
-        return execute(s, input, ctx);
+        return this.executeClosingChannels(s, input, ctx);
+    }
+    /**
+     * Run `execute`, closing the execution's external channels when the
+     * OUTERMOST run on a root context finishes (spec 06 Lifecycle: handles flip
+     * `closed`, channel streams end). Patterns re-enter `run()` with the same
+     * root context (`ctx.harness.run(step, input, ctx)`), so a depth count —
+     * not the return itself — marks root completion. Child-context runs never
+     * close anything.
+     */
+    async executeClosingChannels(s, input, ctx) {
+        if (ctx.parent !== null) {
+            return execute(s, input, ctx);
+        }
+        const depth = this.rootRunDepth.get(ctx.id) ?? 0;
+        if (depth === 0) {
+            // A restored or sequentially re-run root context reuses its id — clear
+            // any closure from a previous completion so its channels work again.
+            this.channelStore.openExecution(ctx.id);
+        }
+        this.rootRunDepth.set(ctx.id, depth + 1);
+        try {
+            return await execute(s, input, ctx);
+        }
+        finally {
+            const remaining = (this.rootRunDepth.get(ctx.id) ?? 1) - 1;
+            if (remaining > 0) {
+                this.rootRunDepth.set(ctx.id, remaining);
+            }
+            else {
+                this.rootRunDepth.delete(ctx.id);
+                this.channelStore.closeExecution(ctx.id);
+            }
+        }
     }
     /**
      * Idempotently run layer `init` hooks for `ctx` (keyed by `ctx.id`). Init
@@ -512,6 +547,9 @@ export class AgentHarness {
     getChannelHandle(channel, executionId) {
         return this.channelStore.getHandle(channel, executionId);
     }
+    getChannelStream(channel, executionId) {
+        return this.channelStore.subscribe(channel, executionId);
+    }
     /** Resolves layer-provided tools and merges with step tools into ctx.unifiedTools. */
     setUnifiedTools(ctx, stepTools) {
         const layers = ctx.layers;
@@ -744,6 +782,11 @@ export class AgentHarness {
         for (const node of tree.reverse()) {
             await this.teardownCancelledContext(node);
         }
+        // Cancellation completes the root execution (spec 06 Lifecycle): close
+        // its external channels so handles flip `closed` and streams end.
+        if (ctx.parent === null) {
+            this.channelStore.closeExecution(ctx.id);
+        }
     }
     /**
      * Run the layer lifecycle's abort path for one cancelled context:

package/dist/runtime/channel-store.d.ts

@@ -12,6 +12,15 @@ export interface ChannelSendOpts {
 export declare class ChannelStore {
     private channels;
     private closedExecutions;
+    /**
+     * Ids a `ChannelHandle` was issued for. Handles have no dispose lifecycle,
+     * so these are the only ids whose closure must be durably recorded (for
+     * `handle.closed` / `channel_closed`). Streams are closed directly through
+     * `subscribersByExecution`, so stream-only ids never accumulate here — a
+     * session harness closing one root id per turn stays bounded.
+     */
+    private handleObserved;
+    private subscribersByExecution;
     private getOrCreate;
     /**
      * Subscribe to wake notifications on a channel without consuming any value.
@@ -53,6 +62,30 @@ export declare class ChannelStore {
      * dropped (with a warning) so external callers never block.
      */
     private sendExternal;
+    /**
+     * External-reader subscription (spec 06, External Subscriptions). Delivery
+     * by mode: `topic` is a persistent non-lossy tap (per-subscriber bounded
+     * buffer, no replay of pre-subscribe values), `queue` competes with internal
+     * `recv` waiters FIFO (external consumption frees parked senders), `value`
+     * yields the current value then conflated updates.
+     *
+     * Channel state is keyed by NAME — `executionId` bounds only the
+     * subscription's lifetime (it ends when `closeExecution(executionId)`
+     * runs; queued values present at close drain first), never which values
+     * are delivered. An id that is never closed yields an unbounded stream
+     * the caller ends with `iterator.return()`. External waiters never time
+     * out — they end via close instead. The returned iterable owns a single
+     * iterator (generator semantics): subscribe again for a second consumer.
+     */
+    subscribe<T>(channel: ExternalChannel<T>, executionId: string): AsyncIterable<T>;
+    /** Shift the queue head and promote the oldest parked sender into the freed slot. */
+    private dequeueHead;
     getHandle<T>(channel: ExternalChannel<T>, executionId: string): ChannelHandle<T>;
     closeExecution(executionId: string): void;
+    /**
+     * A root run is (re)starting on this execution id: clear any previous
+     * closure so checkpoint-restored and sequentially re-run root contexts get
+     * working channels again instead of a permanently poisoned id.
+     */
+    openExecution(executionId: string): void;
 }

package/dist/runtime/channel-store.js

@@ -12,6 +12,15 @@ function cancelledError(signal) {
 export class ChannelStore {
     channels = new Map();
     closedExecutions = new Set();
+    /**
+     * Ids a `ChannelHandle` was issued for. Handles have no dispose lifecycle,
+     * so these are the only ids whose closure must be durably recorded (for
+     * `handle.closed` / `channel_closed`). Streams are closed directly through
+     * `subscribersByExecution`, so stream-only ids never accumulate here — a
+     * session harness closing one root id per turn stays bounded.
+     */
+    handleObserved = new Set();
+    subscribersByExecution = new Map();
     getOrCreate(channel) {
         let state = frameworkCast(this.channels.get(channel.name));
         if (!state) {
@@ -25,6 +34,7 @@ export class ChannelStore {
                 pendingSenders: [],
                 topicSubscribers: new Set(),
                 wakeSubscribers: new Set(),
+                externalSubscribers: new Set(),
             };
             this.channels.set(channel.name, frameworkCast(state));
         }
@@ -79,6 +89,9 @@ export class ChannelStore {
                         waiter.resolve(value);
                     }
                 }
+                for (const sub of state.externalSubscribers) {
+                    sub.push(value);
+                }
                 break;
             case 'queue':
                 if (state.queueWaiters.length > 0) {
@@ -96,6 +109,9 @@ export class ChannelStore {
                 for (const sub of state.topicSubscribers) {
                     sub(value);
                 }
+                for (const sub of state.externalSubscribers) {
+                    sub.push(value);
+                }
                 break;
         }
         this.fireWakes(state);
@@ -206,10 +222,9 @@ export class ChannelStore {
                 }
                 return this.waitWithTimeout(state.valueWaiters, channel.name, timeout, signal);
             case 'queue': {
-                if (state.queue.length > 0) {
-                    const head = state.queue.shift();
-                    this.promotePendingSender(state);
-                    return head;
+                const head = this.dequeueHead(state);
+                if (head) {
+                    return head.value;
                 }
                 // capacity-0 edge: senders can be parked while the queue is empty —
                 // hand the oldest parked value straight to this receiver.
@@ -268,12 +283,10 @@ export class ChannelStore {
             case 'value':
                 return state.hasValue ? state.currentValue : null;
             case 'queue': {
-                if (state.queue.length > 0) {
-                    const head = state.queue.shift();
-                    this.promotePendingSender(state);
-                    return head;
-                }
-                return null;
+                // Explicit head check (not `?? null`): a stored `undefined` must come
+                // back as `undefined`, distinguishable from the empty-queue sentinel.
+                const head = this.dequeueHead(state);
+                return head ? head.value : null;
             }
             case 'topic':
                 return null;
@@ -359,7 +372,96 @@ export class ChannelStore {
         // synchronously — nothing can park here.
         void this.send(channel, value);
     }
+    /**
+     * External-reader subscription (spec 06, External Subscriptions). Delivery
+     * by mode: `topic` is a persistent non-lossy tap (per-subscriber bounded
+     * buffer, no replay of pre-subscribe values), `queue` competes with internal
+     * `recv` waiters FIFO (external consumption frees parked senders), `value`
+     * yields the current value then conflated updates.
+     *
+     * Channel state is keyed by NAME — `executionId` bounds only the
+     * subscription's lifetime (it ends when `closeExecution(executionId)`
+     * runs; queued values present at close drain first), never which values
+     * are delivered. An id that is never closed yields an unbounded stream
+     * the caller ends with `iterator.return()`. External waiters never time
+     * out — they end via close instead. The returned iterable owns a single
+     * iterator (generator semantics): subscribe again for a second consumer.
+     */
+    subscribe(channel, executionId) {
+        if (this.closedExecutions.has(executionId)) {
+            return CLOSED_ITERABLE;
+        }
+        const state = this.getOrCreate(channel);
+        const subscriber = new ExternalSubscriber({
+            channelName: channel.name,
+            conflate: state.mode === 'value',
+            takeShared: state.mode === 'queue'
+                ? () => {
+                    const head = this.dequeueHead(state);
+                    if (head) {
+                        return head;
+                    }
+                    // capacity-0 edge: hand a parked sender's value straight over.
+                    const sender = state.pendingSenders.shift();
+                    if (!sender) {
+                        return null;
+                    }
+                    sender.resolve();
+                    return {
+                        value: sender.value,
+                    };
+                }
+                : undefined,
+            parkShared: state.mode === 'queue'
+                ? (waiter) => {
+                    state.queueWaiters.push(waiter);
+                    return () => {
+                        const idx = state.queueWaiters.indexOf(waiter);
+                        if (idx >= 0) {
+                            state.queueWaiters.splice(idx, 1);
+                        }
+                    };
+                }
+                : undefined,
+            onFinish: () => {
+                state.externalSubscribers.delete(subscriber);
+                const byExecution = this.subscribersByExecution.get(executionId);
+                if (byExecution) {
+                    byExecution.delete(erased);
+                    if (byExecution.size === 0) {
+                        this.subscribersByExecution.delete(executionId);
+                    }
+                }
+            },
+        });
+        const erased = frameworkCast(subscriber);
+        if (state.mode !== 'queue') {
+            state.externalSubscribers.add(subscriber);
+        }
+        if (state.mode === 'value' && state.hasValue) {
+            subscriber.push(state.currentValue);
+        }
+        let byExecution = this.subscribersByExecution.get(executionId);
+        if (!byExecution) {
+            byExecution = new Set();
+            this.subscribersByExecution.set(executionId, byExecution);
+        }
+        byExecution.add(erased);
+        return subscriber;
+    }
+    /** Shift the queue head and promote the oldest parked sender into the freed slot. */
+    dequeueHead(state) {
+        if (state.queue.length === 0) {
+            return null;
+        }
+        const head = state.queue.shift();
+        this.promotePendingSender(state);
+        return {
+            value: head,
+        };
+    }
     getHandle(channel, executionId) {
+        this.handleObserved.add(executionId);
         const store = this;
         return {
             get closed() {
@@ -378,6 +480,190 @@ export class ChannelStore {
         };
     }
     closeExecution(executionId) {
-        this.closedExecutions.add(executionId);
+        // Closure is durably recorded only for ids with issued handles — see
+        // `handleObserved`. Consequence: a handle taken AFTER an execution
+        // completed reads `closed === false`, and a stream subscribed after a
+        // stream-only execution completed waits instead of ending; take handles
+        // and subscribe before running.
+        if (this.handleObserved.has(executionId)) {
+            this.closedExecutions.add(executionId);
+        }
+        const subscribers = this.subscribersByExecution.get(executionId);
+        if (!subscribers) {
+            return;
+        }
+        this.subscribersByExecution.delete(executionId);
+        for (const subscriber of subscribers) {
+            subscriber.close();
+        }
+    }
+    /**
+     * A root run is (re)starting on this execution id: clear any previous
+     * closure so checkpoint-restored and sequentially re-run root contexts get
+     * working channels again instead of a permanently poisoned id.
+     */
+    openExecution(executionId) {
+        this.closedExecutions.delete(executionId);
+    }
+}
+const MAX_EXTERNAL_BUFFER = 1_000;
+const CLOSED_ITERABLE = {
+    [Symbol.asyncIterator]() {
+        return this;
+    },
+    next() {
+        return Promise.resolve({
+            value: undefined,
+            done: true,
+        });
+    },
+};
+/**
+ * The iterator behind `ChannelStore.subscribe`. Topic/value subscribers are
+ * push-fed via `push()`; queue subscribers pull from the shared queue state so
+ * they compete fairly with internal `recv` waiters. `close()` (execution
+ * completed) lets already-buffered values drain before ending; `return()`
+ * (consumer walked away) drops them.
+ */
+class ExternalSubscriber {
+    opts;
+    buffer = [];
+    waiters = [];
+    parked = [];
+    done = false;
+    /** Consumer called return(): stop pulling from the shared queue. */
+    detached = false;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    /** Deliver a value to this subscriber (topic/value modes). */
+    push(value) {
+        if (this.done) {
+            return;
+        }
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter({
+                value,
+                done: false,
+            });
+            return;
+        }
+        if (this.opts.conflate) {
+            this.buffer = [
+                value,
+            ];
+            return;
+        }
+        if (this.buffer.length >= MAX_EXTERNAL_BUFFER) {
+            console.warn(`[noetic] Channel '${this.opts.channelName}': external subscriber buffer at capacity (${MAX_EXTERNAL_BUFFER}), dropping oldest value.`);
+            this.buffer.shift();
+        }
+        this.buffer.push(value);
+    }
+    next() {
+        if (this.buffer.length > 0) {
+            return Promise.resolve({
+                value: this.buffer.shift(),
+                done: false,
+            });
+        }
+        // Live shared-queue reads stop at close — close() snapshots the queue
+        // into this.buffer, so a closed iterator can never steal values sent to
+        // a later execution on the same channel name.
+        const taken = this.done ? null : this.opts.takeShared?.();
+        if (taken) {
+            return Promise.resolve({
+                value: taken.value,
+                done: false,
+            });
+        }
+        if (this.done) {
+            return Promise.resolve({
+                value: undefined,
+                done: true,
+            });
+        }
+        if (this.opts.parkShared) {
+            return this.parkInSharedQueue(this.opts.parkShared);
+        }
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+    }
+    return() {
+        this.detached = true;
+        this.buffer = [];
+        this.close();
+        return Promise.resolve({
+            value: undefined,
+            done: true,
+        });
+    }
+    /** End the iterator: settle every pending `next()` and unregister. Buffered values still drain. */
+    close() {
+        if (this.done) {
+            return;
+        }
+        // Snapshot the shared queue's current contents into the private buffer
+        // ("buffered values drain first") — after this the iterator never touches
+        // live channel state again. A detached iterator (return()) walked away
+        // and drains nothing.
+        if (!this.detached && this.opts.takeShared) {
+            for (let taken = this.opts.takeShared(); taken; taken = this.opts.takeShared()) {
+                this.buffer.push(taken.value);
+            }
+        }
+        this.done = true;
+        this.opts.onFinish();
+        for (const entry of this.parked.splice(0)) {
+            entry.unpark();
+            entry.settleDone();
+        }
+        for (const waiter of this.waiters.splice(0)) {
+            waiter({
+                value: undefined,
+                done: true,
+            });
+        }
+    }
+    /**
+     * Queue mode: wait in the channel's shared waiter FIFO. No timer attaches,
+     * so external waiters never reject with `channel_timeout` — `close()` ends
+     * them instead.
+     */
+    parkInSharedQueue(parkShared) {
+        return new Promise((resolve) => {
+            const entry = {
+                unpark: () => { },
+                settleDone: () => resolve({
+                    value: undefined,
+                    done: true,
+                }),
+            };
+            const removeParked = () => {
+                const idx = this.parked.indexOf(entry);
+                if (idx >= 0) {
+                    this.parked.splice(idx, 1);
+                }
+            };
+            entry.unpark = parkShared({
+                resolve: (value) => {
+                    removeParked();
+                    resolve({
+                        value,
+                        done: false,
+                    });
+                },
+                reject: () => {
+                    removeParked();
+                    entry.settleDone();
+                },
+            });
+            this.parked.push(entry);
+        });
     }
 }

package/package.json

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