@noetic-tools/core 0.0.1

package/dist/runtime/broadcaster-utils.d.ts

@@ -0,0 +1,30 @@
+import type { Context } from '../types/context';
+import type { EventBroadcaster } from './event-broadcaster';
+/** @internal Option controlling framework event emission on a step or callModel request. */
+export type EmitOption = boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
+/**
+ * Check whether a framework event should be emitted given an emit option.
+ *
+ * When `emit` is `undefined` (the default for non-LLM steps where the
+ * field does not exist on the Step type), events are always emitted.
+ * Only StepLLM exposes `emit` for opt-out or filtering.
+ *
+ * @internal
+ */
+export declare function shouldEmit(emit: EmitOption | undefined, eventType: string, data: Record<string, unknown>): boolean;
+/**
+ * Get the EventBroadcaster from a context if available.
+ * Uses property check rather than instanceof to support mock contexts in tests.
+ * @internal
+ */
+export declare function getBroadcaster(ctx?: Context): EventBroadcaster | undefined;
+/**
+ * Emit a framework event to the broadcaster if available.
+ * @internal
+ */
+export declare function emitFrameworkEvent(opts: {
+    broadcaster: EventBroadcaster | undefined;
+    agentName: string;
+    eventType: string;
+    data: Record<string, unknown>;
+}): void;

package/dist/runtime/broadcaster-utils.js

@@ -0,0 +1,53 @@
+//#endregion
+//#region Public API
+/**
+ * Check whether a framework event should be emitted given an emit option.
+ *
+ * When `emit` is `undefined` (the default for non-LLM steps where the
+ * field does not exist on the Step type), events are always emitted.
+ * Only StepLLM exposes `emit` for opt-out or filtering.
+ *
+ * @internal
+ */
+export function shouldEmit(emit, eventType, data) {
+    if (emit === undefined || emit === true) {
+        return true;
+    }
+    if (emit === false) {
+        return false;
+    }
+    return emit(eventType, data);
+}
+/** Typeguard: context carries an internal _broadcaster property. */
+function hasBroadcaster(ctx) {
+    if (!('_broadcaster' in ctx)) {
+        return false;
+    }
+    return typeof ctx._broadcaster === 'object' && ctx._broadcaster !== null;
+}
+/**
+ * Get the EventBroadcaster from a context if available.
+ * Uses property check rather than instanceof to support mock contexts in tests.
+ * @internal
+ */
+export function getBroadcaster(ctx) {
+    if (!ctx) {
+        return undefined;
+    }
+    if (hasBroadcaster(ctx)) {
+        return ctx._broadcaster;
+    }
+    return undefined;
+}
+/**
+ * Emit a framework event to the broadcaster if available.
+ * @internal
+ */
+export function emitFrameworkEvent(opts) {
+    opts.broadcaster?.emit({
+        source: 'framework',
+        type: `${opts.agentName}:${opts.eventType}`,
+        data: opts.data,
+    });
+}
+//#endregion

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

@@ -0,0 +1,18 @@
+import type { Channel, ChannelHandle, ExternalChannel } from '../types/channel';
+export declare class ChannelStore {
+    private channels;
+    private closedExecutions;
+    private getOrCreate;
+    /**
+     * Subscribe to wake notifications on a channel without consuming any value.
+     * Fired once on the next `send()` for any mode, then auto-removed. Returns
+     * an `unsubscribe` so the caller can detach if it cancels first.
+     */
+    subscribeWake<T>(channel: Channel<T>, callback: () => void): () => void;
+    send<T>(channel: Channel<T>, value: T): void;
+    recv<T>(channel: Channel<T>, timeout?: number): Promise<T>;
+    tryRecv<T>(channel: Channel<T>): T | null;
+    private waitWithTimeout;
+    getHandle<T>(channel: ExternalChannel<T>, executionId: string): ChannelHandle<T>;
+    closeExecution(executionId: string): void;
+}

package/dist/runtime/channel-store.js

@@ -0,0 +1,187 @@
+import { NoeticErrorImpl } from '../errors/noetic-error';
+import { frameworkCast } from '../interpreter/framework-cast';
+function isExternalChannel(ch) {
+    return 'external' in ch && ch.external === true;
+}
+const MAX_TOPIC_TIMEOUT = 300_000; // 5 minutes
+export class ChannelStore {
+    channels = new Map();
+    closedExecutions = new Set();
+    getOrCreate(channel) {
+        let state = frameworkCast(this.channels.get(channel.name));
+        if (!state) {
+            state = {
+                mode: channel.mode,
+                hasValue: false,
+                valueWaiters: [],
+                queue: [],
+                capacity: channel.capacity ?? 1_000,
+                queueWaiters: [],
+                topicSubscribers: new Set(),
+                wakeSubscribers: new Set(),
+            };
+            this.channels.set(channel.name, frameworkCast(state));
+        }
+        return state;
+    }
+    /**
+     * Subscribe to wake notifications on a channel without consuming any value.
+     * Fired once on the next `send()` for any mode, then auto-removed. Returns
+     * an `unsubscribe` so the caller can detach if it cancels first.
+     */
+    subscribeWake(channel, callback) {
+        const state = this.getOrCreate(channel);
+        // Capture the set the callback is added to. `send()` swaps in a fresh set
+        // before firing, so once a wake fires the captured `subscribers` is the
+        // *old* set — this unsubscribe is then a no-op, which is correct.
+        const subscribers = state.wakeSubscribers;
+        subscribers.add(callback);
+        return () => {
+            subscribers.delete(callback);
+        };
+    }
+    send(channel, value) {
+        const state = this.getOrCreate(channel);
+        switch (state.mode) {
+            case 'value':
+                state.currentValue = value;
+                state.hasValue = true;
+                if (state.valueWaiters.length > 0) {
+                    state.valueWaiters.shift().resolve(value);
+                }
+                break;
+            case 'queue':
+                if (state.queueWaiters.length > 0) {
+                    state.queueWaiters.shift().resolve(value);
+                }
+                else if (state.queue.length < state.capacity) {
+                    state.queue.push(value);
+                }
+                else {
+                    // At capacity
+                    console.warn(`[noetic] Channel '${channel.name}': queue at capacity (${state.capacity}), dropping message.`);
+                    if (isExternalChannel(channel)) {
+                        state.queue.shift();
+                        state.queue.push(value);
+                    }
+                    // For internal, drop the new value
+                }
+                break;
+            case 'topic':
+                for (const sub of state.topicSubscribers) {
+                    sub(value);
+                }
+                break;
+        }
+        if (state.wakeSubscribers.size > 0) {
+            // Swap in a fresh set before firing so a callback that re-subscribes
+            // (typical for `every` re-arming on its next iteration) lands on the
+            // new set and survives until the next send.
+            const wakers = state.wakeSubscribers;
+            state.wakeSubscribers = new Set();
+            for (const wake of wakers) {
+                wake();
+            }
+        }
+    }
+    async recv(channel, timeout = 30_000) {
+        const state = this.getOrCreate(channel);
+        switch (state.mode) {
+            case 'value':
+                if (state.hasValue) {
+                    return state.currentValue;
+                }
+                return this.waitWithTimeout(state.valueWaiters, channel.name, timeout);
+            case 'queue':
+                if (state.queue.length > 0) {
+                    return state.queue.shift();
+                }
+                return this.waitWithTimeout(state.queueWaiters, channel.name, timeout);
+            case 'topic': {
+                // Clamp timeout to prevent indefinite subscriber leaks
+                let effectiveTimeout = timeout;
+                if (effectiveTimeout <= 0) {
+                    console.warn(`[noetic] Channel '${channel.name}': topic recv with non-positive timeout, clamping to ${MAX_TOPIC_TIMEOUT}ms`);
+                    effectiveTimeout = MAX_TOPIC_TIMEOUT;
+                }
+                return new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => {
+                        state.topicSubscribers.delete(handler);
+                        reject(new NoeticErrorImpl({
+                            kind: 'channel_timeout',
+                            channelName: channel.name,
+                            timeout: effectiveTimeout,
+                        }));
+                    }, effectiveTimeout);
+                    const handler = (value) => {
+                        clearTimeout(timer);
+                        state.topicSubscribers.delete(handler);
+                        resolve(value);
+                    };
+                    state.topicSubscribers.add(handler);
+                });
+            }
+        }
+    }
+    tryRecv(channel) {
+        const state = this.getOrCreate(channel);
+        switch (state.mode) {
+            case 'value':
+                return state.hasValue ? state.currentValue : null;
+            case 'queue':
+                return state.queue.length > 0 ? state.queue.shift() : null;
+            case 'topic':
+                return null;
+        }
+    }
+    waitWithTimeout(waiters, channelName, timeout) {
+        return new Promise((resolve, reject) => {
+            let timer = null;
+            const wrappedResolve = (v) => {
+                if (timer) {
+                    clearTimeout(timer);
+                }
+                resolve(v);
+            };
+            const entry = {
+                resolve: wrappedResolve,
+                reject,
+            };
+            waiters.push(entry);
+            if (timeout > 0) {
+                timer = setTimeout(() => {
+                    const idx = waiters.indexOf(entry);
+                    if (idx >= 0) {
+                        waiters.splice(idx, 1);
+                        reject(new NoeticErrorImpl({
+                            kind: 'channel_timeout',
+                            channelName,
+                            timeout,
+                        }));
+                    }
+                }, timeout);
+            }
+        });
+    }
+    getHandle(channel, executionId) {
+        const store = this;
+        return {
+            get closed() {
+                return store.closedExecutions.has(executionId);
+            },
+            channel,
+            send(value) {
+                if (store.closedExecutions.has(executionId)) {
+                    throw new NoeticErrorImpl({
+                        kind: 'channel_closed',
+                        channelName: channel.name,
+                    });
+                }
+                store.send(channel, value);
+            },
+        };
+    }
+    closeExecution(executionId) {
+        this.closedExecutions.add(executionId);
+    }
+}

package/dist/runtime/context-impl.d.ts

@@ -0,0 +1,80 @@
+import type { ItemSchemaRegistry } from '../schemas/item';
+import type { Channel } from '../types/channel';
+import type { StepMeta, TokenUsage, Tool } from '../types/common';
+import type { Context, CwdState, ItemLog, LastLayerUsage } from '../types/context';
+import type { FsAdapter } from '../types/fs-adapter';
+import type { Item } from '../types/items';
+import type { ContextMemory, MemoryLayer } from '../types/memory';
+import type { Span } from '../types/observability';
+import type { AgentHarnessContract } from '../types/runtime';
+import type { ChannelStore } from './channel-store';
+import type { EventBroadcaster } from './event-broadcaster';
+export declare class ContextImpl implements Context<ContextMemory> {
+    readonly id: string;
+    stepCount: number;
+    tokens: TokenUsage;
+    cost: number;
+    state: unknown;
+    readonly parent: Context<ContextMemory> | null;
+    readonly depth: number;
+    readonly span: Span;
+    readonly threadId: string;
+    readonly resourceId?: string;
+    readonly itemLog: ItemLog;
+    lastStepMeta: StepMeta | null;
+    lastLayerUsage: LastLayerUsage | undefined;
+    readonly harness: AgentHarnessContract;
+    readonly layers?: MemoryLayer[];
+    unifiedTools?: ReadonlyArray<Tool>;
+    readonly itemSchemas?: ItemSchemaRegistry;
+    readonly cwdState: CwdState;
+    /** @internal Event broadcaster for streaming — not part of public Context interface. */
+    readonly _broadcaster?: EventBroadcaster;
+    private readonly _createdAt;
+    /**
+     * Shared channel store for cross-context communication. Inherited by
+     * `fork` / `spawn` children so channels published by a sibling are visible
+     * to peers — see `interpreter/execute-fork.ts` and `interpreter/execute-spawn.ts`.
+     * @internal
+     */
+    readonly channelStore?: ChannelStore;
+    private _checkpointFn?;
+    private _completionValue?;
+    private _completed;
+    private _aborted;
+    private _abortReason?;
+    private _memory?;
+    constructor(opts: {
+        harness: AgentHarnessContract;
+        parent?: Context;
+        items?: Item[];
+        state?: unknown;
+        threadId?: string;
+        resourceId?: string;
+        span?: Span;
+        channelStore?: ChannelStore;
+        checkpointFn?: () => Promise<void>;
+        layers?: MemoryLayer[];
+        unifiedTools?: ReadonlyArray<Tool>;
+        itemSchemas?: ItemSchemaRegistry;
+        cwdState?: CwdState;
+        _broadcaster?: EventBroadcaster;
+    });
+    get elapsed(): number;
+    get aborted(): boolean;
+    get fs(): FsAdapter;
+    get shell(): AgentHarnessContract['shell'];
+    get subprocess(): AgentHarnessContract['subprocess'];
+    get memory(): ContextMemory;
+    recv<T>(ch: Channel<T>, opts?: {
+        timeout?: number;
+    }): Promise<T>;
+    send<T>(ch: Channel<T>, value: T): void;
+    tryRecv<T>(ch: Channel<T>): T | null;
+    checkpoint(): Promise<void>;
+    complete<T>(value: T): void;
+    get completed(): boolean;
+    get completionValue(): unknown;
+    get abortReason(): string | undefined;
+    abort(reason?: string): void;
+}

package/dist/runtime/context-impl.js

@@ -0,0 +1,140 @@
+import { buildContextMemory } from '../memory/layer-api';
+import { defaultItemSchemaRegistry } from '../schemas/item';
+import { ItemLogImpl } from './item-log-impl';
+const EMPTY_MEMORY = Object.freeze({});
+class NoopSpan {
+    traceId = crypto.randomUUID();
+    spanId = crypto.randomUUID();
+    parentSpanId = null;
+    setAttribute(_key, _value) { }
+    addEvent(_name, _attributes) { }
+    end() { }
+}
+export class ContextImpl {
+    id;
+    stepCount = 0;
+    tokens = {
+        input: 0,
+        output: 0,
+        total: 0,
+    };
+    cost = 0;
+    state;
+    parent;
+    depth;
+    span;
+    threadId;
+    resourceId;
+    itemLog;
+    lastStepMeta = null;
+    lastLayerUsage = undefined;
+    harness;
+    layers;
+    unifiedTools;
+    itemSchemas;
+    cwdState;
+    /** @internal Event broadcaster for streaming — not part of public Context interface. */
+    _broadcaster;
+    _createdAt;
+    /**
+     * Shared channel store for cross-context communication. Inherited by
+     * `fork` / `spawn` children so channels published by a sibling are visible
+     * to peers — see `interpreter/execute-fork.ts` and `interpreter/execute-spawn.ts`.
+     * @internal
+     */
+    channelStore;
+    _checkpointFn;
+    _completionValue;
+    _completed = false;
+    _aborted = false;
+    _abortReason;
+    _memory;
+    constructor(opts) {
+        this.id = crypto.randomUUID();
+        this._createdAt = Date.now();
+        this.harness = opts.harness;
+        this.state = opts.state ?? {};
+        this.parent = opts.parent ?? null;
+        this.depth = this.parent ? this.parent.depth + 1 : 0;
+        this.span = opts.span ?? new NoopSpan();
+        this.threadId = opts.threadId ?? crypto.randomUUID();
+        this.resourceId = opts.resourceId;
+        this.channelStore = opts.channelStore;
+        this._checkpointFn = opts.checkpointFn;
+        this.layers = opts.layers;
+        this.unifiedTools = opts.unifiedTools;
+        this.itemSchemas = opts.itemSchemas ?? defaultItemSchemaRegistry;
+        this.cwdState = opts.cwdState ?? {
+            cwd: process.cwd(),
+        };
+        this._broadcaster = opts._broadcaster;
+        const log = new ItemLogImpl(this.itemSchemas);
+        if (opts.items) {
+            for (const item of opts.items) {
+                log.append(item);
+            }
+        }
+        this.itemLog = log;
+    }
+    get elapsed() {
+        return Date.now() - this._createdAt;
+    }
+    get aborted() {
+        return this._aborted;
+    }
+    get fs() {
+        return this.harness.fs;
+    }
+    get shell() {
+        return this.harness.shell;
+    }
+    get subprocess() {
+        return this.harness.subprocess;
+    }
+    get memory() {
+        if (!this._memory) {
+            this._memory = this.layers ? buildContextMemory(this.layers, this) : EMPTY_MEMORY;
+        }
+        return this._memory;
+    }
+    recv(ch, opts) {
+        if (!this.channelStore) {
+            return Promise.reject(new Error('No channel store configured'));
+        }
+        return this.channelStore.recv(ch, opts?.timeout);
+    }
+    send(ch, value) {
+        if (!this.channelStore) {
+            throw new Error('No channel store configured');
+        }
+        this.channelStore.send(ch, value);
+    }
+    tryRecv(ch) {
+        if (!this.channelStore) {
+            throw new Error('No channel store configured');
+        }
+        return this.channelStore.tryRecv(ch);
+    }
+    async checkpoint() {
+        if (this._checkpointFn) {
+            await this._checkpointFn();
+        }
+    }
+    complete(value) {
+        this._completed = true;
+        this._completionValue = value;
+    }
+    get completed() {
+        return this._completed;
+    }
+    get completionValue() {
+        return this._completionValue;
+    }
+    get abortReason() {
+        return this._abortReason;
+    }
+    abort(reason) {
+        this._aborted = true;
+        this._abortReason = reason;
+    }
+}

package/dist/runtime/cwd-helpers.d.ts

@@ -0,0 +1,42 @@
+import type { Context, CwdState } from '../types/context';
+/**
+ * @public Resolve the live cwd for a tool execution. Falls back to the
+ * tool's factory-time cwd (then `process.cwd()`) so partial test contexts
+ * without a `cwdState` keep working.
+ */
+export declare function getToolCwd(ctx: Context | undefined, fallback?: string): string;
+/**
+ * @public Update the shared cwd state for a Context. Callers MUST pass an
+ * absolute, normalized path — validation (`statSync`, `~` expansion, etc.)
+ * is the caller's responsibility.
+ *
+ * No-op when `nextCwd` equals the current cwd: leaves `previousCwd` alone
+ * so a `cd .` (or any redundant cd to the same path) does not stomp the
+ * preserved OLDPWD that powers `cd -`.
+ */
+export declare function setToolCwd(ctx: Context, nextCwd: string): {
+    previousCwd: string;
+    newCwd: string;
+};
+/**
+ * @public Snapshot a parent's cwd state for a child Context. Spawned/forked
+ * children must not share the parent's `CwdState` reference — POSIX-fork
+ * semantics require child mutations stay local to the child.
+ */
+export declare function snapshotCwdState(parent: Context): CwdState;
+/**
+ * @internal Briefly retarget `cwdState.cwd` so an immediately-following
+ * `executeSpawn` snapshots `nextCwd` onto the spawned child, then restore
+ * the parent's prior cwd via the returned callback.
+ *
+ * Unlike {@link setToolCwd}, this does NOT update `previousCwd` — the
+ * retarget is invisible to the parent's logical cd history (it only exists
+ * to seed the child's snapshot). The bypass is the entire reason this
+ * helper is separate from `setToolCwd`.
+ *
+ * Safe ONLY when the caller holds exclusive use of the context for the
+ * duration of the retarget — typically a sync spawn that awaits before
+ * restoring. `harness.run()` returns a Promise (not an iterator) so no
+ * yield occurs between retarget and restore.
+ */
+export declare function retargetCwdForSpawn(ctx: Context, nextCwd: string): () => void;

package/dist/runtime/cwd-helpers.js

@@ -0,0 +1,68 @@
+/**
+ * @public Resolve the live cwd for a tool execution. Falls back to the
+ * tool's factory-time cwd (then `process.cwd()`) so partial test contexts
+ * without a `cwdState` keep working.
+ */
+export function getToolCwd(ctx, fallback) {
+    return ctx?.cwdState?.cwd ?? fallback ?? process.cwd();
+}
+/**
+ * @public Update the shared cwd state for a Context. Callers MUST pass an
+ * absolute, normalized path — validation (`statSync`, `~` expansion, etc.)
+ * is the caller's responsibility.
+ *
+ * No-op when `nextCwd` equals the current cwd: leaves `previousCwd` alone
+ * so a `cd .` (or any redundant cd to the same path) does not stomp the
+ * preserved OLDPWD that powers `cd -`.
+ */
+export function setToolCwd(ctx, nextCwd) {
+    const currentCwd = ctx.cwdState.cwd;
+    if (nextCwd === currentCwd) {
+        return {
+            previousCwd: ctx.cwdState.previousCwd ?? currentCwd,
+            newCwd: currentCwd,
+        };
+    }
+    const previousCwd = ctx.cwdState.cwd;
+    ctx.cwdState.previousCwd = previousCwd;
+    ctx.cwdState.cwd = nextCwd;
+    return {
+        previousCwd,
+        newCwd: nextCwd,
+    };
+}
+/**
+ * @public Snapshot a parent's cwd state for a child Context. Spawned/forked
+ * children must not share the parent's `CwdState` reference — POSIX-fork
+ * semantics require child mutations stay local to the child.
+ */
+export function snapshotCwdState(parent) {
+    return {
+        cwd: parent.cwdState.cwd,
+        previousCwd: parent.cwdState.previousCwd,
+    };
+}
+/**
+ * @internal Briefly retarget `cwdState.cwd` so an immediately-following
+ * `executeSpawn` snapshots `nextCwd` onto the spawned child, then restore
+ * the parent's prior cwd via the returned callback.
+ *
+ * Unlike {@link setToolCwd}, this does NOT update `previousCwd` — the
+ * retarget is invisible to the parent's logical cd history (it only exists
+ * to seed the child's snapshot). The bypass is the entire reason this
+ * helper is separate from `setToolCwd`.
+ *
+ * Safe ONLY when the caller holds exclusive use of the context for the
+ * duration of the retarget — typically a sync spawn that awaits before
+ * restoring. `harness.run()` returns a Promise (not an iterator) so no
+ * yield occurs between retarget and restore.
+ */
+export function retargetCwdForSpawn(ctx, nextCwd) {
+    const savedCwd = ctx.cwdState.cwd;
+    const savedPrev = ctx.cwdState.previousCwd;
+    ctx.cwdState.cwd = nextCwd;
+    return () => {
+        ctx.cwdState.cwd = savedCwd;
+        ctx.cwdState.previousCwd = savedPrev;
+    };
+}

package/dist/runtime/detached-handle.d.ts

@@ -0,0 +1,14 @@
+import type { DetachedHandle } from '../types/detached';
+import { DetachedStatus } from '../types/detached';
+export declare class DetachedHandleImpl<O> implements DetachedHandle<O> {
+    readonly id: string;
+    private _status;
+    private _result;
+    private _error;
+    private readonly promise;
+    constructor(id: string, promise: Promise<O>);
+    get status(): DetachedStatus;
+    get result(): O | undefined;
+    get error(): string | undefined;
+    await(timeout?: number): Promise<O>;
+}

package/dist/runtime/detached-handle.js

@@ -0,0 +1,56 @@
+import { NoeticErrorImpl } from '../errors/noetic-error';
+import { DetachedStatus } from '../types/detached';
+//#region DetachedHandleImpl
+export class DetachedHandleImpl {
+    id;
+    _status = DetachedStatus.Running;
+    _result;
+    _error;
+    promise;
+    constructor(id, promise) {
+        this.id = id;
+        this.promise = promise;
+        promise.then((value) => {
+            this._status = DetachedStatus.Completed;
+            this._result = value;
+        }, (err) => {
+            this._status = DetachedStatus.Failed;
+            this._error = err instanceof Error ? err.message : String(err);
+        });
+    }
+    get status() {
+        return this._status;
+    }
+    get result() {
+        return this._result;
+    }
+    get error() {
+        return this._error;
+    }
+    async await(timeout) {
+        if (timeout === undefined || timeout <= 0) {
+            return this.promise;
+        }
+        let timerId;
+        const timeoutPromise = new Promise((_resolve, reject) => {
+            timerId = setTimeout(() => {
+                reject(new NoeticErrorImpl({
+                    kind: 'step_failed',
+                    stepId: this.id,
+                    cause: new Error(`Detached spawn timed out after ${timeout}ms`),
+                    retriesExhausted: false,
+                }));
+            }, timeout);
+        });
+        try {
+            return await Promise.race([
+                this.promise,
+                timeoutPromise,
+            ]);
+        }
+        finally {
+            clearTimeout(timerId);
+        }
+    }
+}
+//#endregion