@noetic-tools/core 0.0.1

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

@@ -0,0 +1,61 @@
+import type { StreamEvent } from '../types/harness-result';
+interface EventBroadcasterOpts {
+    maxBufferSize?: number;
+}
+/**
+ * Multi-consumer broadcast channel with replay support for streaming events.
+ *
+ * Each consumer gets an independent iterator that replays buffered events
+ * from the start, then receives new events as they are emitted.
+ *
+ * The buffer is bounded to `maxBufferSize` events (default 10,000). When the
+ * buffer exceeds this limit, oldest events are trimmed and iterator cursors
+ * are adjusted. Once all consumers have departed, new events are discarded
+ * to prevent unbounded memory growth. This bounded buffer serves as the
+ * backpressure mechanism — no additional flow control is needed for typical
+ * LLM response sizes.
+ *
+ * @internal
+ */
+export declare class EventBroadcaster {
+    private readonly buffer;
+    private readonly maxBufferSize;
+    private isDone;
+    private err?;
+    private readonly iterators;
+    private hasHadConsumers;
+    constructor(opts?: EventBroadcasterOpts);
+    /** Push an event to all active iterators and the replay buffer. */
+    emit(event: StreamEvent): void;
+    /** Signal that no more events will be emitted. */
+    complete(): void;
+    /** Signal an error to all consumers. */
+    error(err: Error): void;
+    [Symbol.asyncIterator](): AsyncIterator<StreamEvent>;
+    /** @internal Access the buffer for iterators. */
+    getBuffer(): ReadonlyArray<StreamEvent>;
+    /** @internal Check if the broadcaster is finished. */
+    get finished(): boolean;
+    /** @internal Get the error if any. */
+    get streamError(): Error | undefined;
+    /** @internal Remove an iterator from the set. */
+    removeIterator(iter: BroadcastIterator): void;
+    /** @internal Current buffer length (for testing). */
+    get bufferSize(): number;
+}
+declare class BroadcastIterator implements AsyncIterator<StreamEvent> {
+    private cursor;
+    private waiter?;
+    private returned;
+    private readonly broadcaster;
+    constructor(broadcaster: EventBroadcaster);
+    /** Adjust cursor when buffer is trimmed. */
+    adjustCursor(trimCount: number): void;
+    /** Called by the broadcaster when new data or completion is available. */
+    notify(): void;
+    next(): Promise<IteratorResult<StreamEvent>>;
+    throw(err: Error): Promise<IteratorResult<StreamEvent>>;
+    return(): Promise<IteratorResult<StreamEvent>>;
+    private tryRead;
+}
+export {};

package/dist/runtime/event-broadcaster.js

@@ -0,0 +1,187 @@
+//#endregion
+const DEFAULT_MAX_BUFFER_SIZE = 1e4;
+//#region EventBroadcaster
+/**
+ * Multi-consumer broadcast channel with replay support for streaming events.
+ *
+ * Each consumer gets an independent iterator that replays buffered events
+ * from the start, then receives new events as they are emitted.
+ *
+ * The buffer is bounded to `maxBufferSize` events (default 10,000). When the
+ * buffer exceeds this limit, oldest events are trimmed and iterator cursors
+ * are adjusted. Once all consumers have departed, new events are discarded
+ * to prevent unbounded memory growth. This bounded buffer serves as the
+ * backpressure mechanism — no additional flow control is needed for typical
+ * LLM response sizes.
+ *
+ * @internal
+ */
+export class EventBroadcaster {
+    buffer = [];
+    maxBufferSize;
+    isDone = false;
+    err;
+    iterators = new Set();
+    hasHadConsumers = false;
+    constructor(opts) {
+        this.maxBufferSize = opts?.maxBufferSize ?? DEFAULT_MAX_BUFFER_SIZE;
+    }
+    /** Push an event to all active iterators and the replay buffer. */
+    emit(event) {
+        if (this.isDone) {
+            return;
+        }
+        // Skip buffering when all consumers have departed
+        if (this.hasHadConsumers && this.iterators.size === 0) {
+            return;
+        }
+        this.buffer.push(event);
+        // Trim buffer if it exceeds max size
+        if (this.buffer.length > this.maxBufferSize) {
+            const trimCount = this.buffer.length - this.maxBufferSize;
+            this.buffer.splice(0, trimCount);
+            // Adjust all active iterator cursors
+            for (const iter of this.iterators) {
+                iter.adjustCursor(trimCount);
+            }
+        }
+        for (const iter of this.iterators) {
+            iter.notify();
+        }
+    }
+    /** Signal that no more events will be emitted. */
+    complete() {
+        if (this.isDone) {
+            return;
+        }
+        this.isDone = true;
+        for (const iter of this.iterators) {
+            iter.notify();
+        }
+    }
+    /** Signal an error to all consumers. */
+    error(err) {
+        if (this.isDone) {
+            return;
+        }
+        this.isDone = true;
+        this.err = err;
+        for (const iter of this.iterators) {
+            iter.notify();
+        }
+    }
+    [Symbol.asyncIterator]() {
+        this.hasHadConsumers = true;
+        const iter = new BroadcastIterator(this);
+        this.iterators.add(iter);
+        return iter;
+    }
+    /** @internal Access the buffer for iterators. */
+    getBuffer() {
+        return this.buffer;
+    }
+    /** @internal Check if the broadcaster is finished. */
+    get finished() {
+        return this.isDone;
+    }
+    /** @internal Get the error if any. */
+    get streamError() {
+        return this.err;
+    }
+    /** @internal Remove an iterator from the set. */
+    removeIterator(iter) {
+        this.iterators.delete(iter);
+    }
+    /** @internal Current buffer length (for testing). */
+    get bufferSize() {
+        return this.buffer.length;
+    }
+}
+//#endregion
+//#region BroadcastIterator
+class BroadcastIterator {
+    cursor = 0;
+    waiter;
+    returned = false;
+    broadcaster;
+    constructor(broadcaster) {
+        this.broadcaster = broadcaster;
+    }
+    /** Adjust cursor when buffer is trimmed. */
+    adjustCursor(trimCount) {
+        this.cursor = Math.max(0, this.cursor - trimCount);
+    }
+    /** Called by the broadcaster when new data or completion is available. */
+    notify() {
+        if (!this.waiter) {
+            return;
+        }
+        const w = this.waiter;
+        this.waiter = undefined;
+        try {
+            const result = this.tryRead();
+            if (result) {
+                w.resolve(result);
+            }
+        }
+        catch (err) {
+            // Reject the waiter's promise so the error propagates through the async iterator
+            w.reject(err);
+        }
+    }
+    async next() {
+        if (this.returned) {
+            return {
+                done: true,
+                value: undefined,
+            };
+        }
+        const result = this.tryRead();
+        if (result) {
+            return result;
+        }
+        return new Promise((resolve, reject) => {
+            this.waiter = {
+                resolve,
+                reject,
+            };
+        });
+    }
+    async throw(err) {
+        this.returned = true;
+        this.broadcaster.removeIterator(this);
+        throw err;
+    }
+    async return() {
+        this.returned = true;
+        this.broadcaster.removeIterator(this);
+        return {
+            done: true,
+            value: undefined,
+        };
+    }
+    tryRead() {
+        const buffer = this.broadcaster.getBuffer();
+        if (this.cursor < buffer.length) {
+            const event = buffer[this.cursor];
+            this.cursor++;
+            return {
+                done: false,
+                value: event,
+            };
+        }
+        if (this.broadcaster.finished) {
+            this.broadcaster.removeIterator(this);
+            const err = this.broadcaster.streamError;
+            if (err) {
+                throw err;
+            }
+            return {
+                done: true,
+                value: undefined,
+            };
+        }
+        return null;
+    }
+}
+//#endregion

package/dist/runtime/exec-context-factory.d.ts

@@ -0,0 +1,25 @@
+import type { Context } from '../types/context';
+import type { ExecutionContext } from '../types/memory';
+/**
+ * Optional overrides for `contextToExecCtx`. Used by `executeSpawn` to build
+ * parent and child execution contexts that reuse the same tokenize / trace /
+ * layer-state wiring as the main path, but with spawn-specific identity
+ * (`executionId`, `depth`, `stepNumber`, and the scope used for layer-state
+ * reads).
+ */
+export interface ExecCtxOverrides {
+    callModel?: ExecutionContext['callModel'];
+    executionId?: string;
+    depth?: number;
+    stepNumber?: number;
+    tokenUsage?: ExecutionContext['tokenUsage'];
+    cost?: number;
+    /** Execution id to scope `readLayerState` to (defaults to `ctx.id`). */
+    readLayerStateId?: string;
+}
+/**
+ * Maps a full `Context` to the lightweight `ExecutionContext` consumed by memory layer hooks.
+ * Centralised here so the mapping stays consistent across agent-harness, layer-api, and the
+ * spawn interpreter.
+ */
+export declare function contextToExecCtx(ctx: Context, overrides?: ExecCtxOverrides): ExecutionContext;

package/dist/runtime/exec-context-factory.js

@@ -0,0 +1,30 @@
+import { estimateTokens } from '../interpreter/message-helpers';
+/**
+ * Maps a full `Context` to the lightweight `ExecutionContext` consumed by memory layer hooks.
+ * Centralised here so the mapping stays consistent across agent-harness, layer-api, and the
+ * spawn interpreter.
+ */
+export function contextToExecCtx(ctx, overrides) {
+    const readLayerStateId = overrides?.readLayerStateId ?? ctx.id;
+    return {
+        executionId: overrides?.executionId ?? ctx.id,
+        threadId: ctx.threadId,
+        resourceId: ctx.resourceId,
+        depth: overrides?.depth ?? ctx.depth,
+        stepNumber: overrides?.stepNumber ?? ctx.stepCount,
+        tokenUsage: overrides?.tokenUsage ?? {
+            input: ctx.tokens.input,
+            output: ctx.tokens.output,
+        },
+        cost: overrides?.cost ?? ctx.cost,
+        fs: ctx.harness.fs,
+        shell: ctx.harness.shell,
+        callModel: overrides?.callModel,
+        tokenize: estimateTokens,
+        trace: {
+            setAttribute: (key, value) => ctx.span.setAttribute(key, value),
+            addEvent: (name, attributes) => ctx.span.addEvent(name, attributes),
+        },
+        readLayerState: (layerId) => ctx.harness.getLayerState(readLayerStateId, layerId),
+    };
+}

package/dist/runtime/in-memory-storage.d.ts

@@ -0,0 +1,9 @@
+import type { StorageAdapter } from '../types/memory';
+/**
+ * @public Process-local, Map-backed StorageAdapter.
+ *
+ * The default when no storage is configured on AgentHarness. State lives only
+ * for the lifetime of the Map (i.e., this harness instance). Durable backends
+ * must be supplied explicitly by the caller.
+ */
+export declare function createInMemoryStorage(): StorageAdapter;

package/dist/runtime/in-memory-storage.js

@@ -0,0 +1,33 @@
+import { frameworkCast } from '../interpreter/framework-cast';
+//#region Public API
+/**
+ * @public Process-local, Map-backed StorageAdapter.
+ *
+ * The default when no storage is configured on AgentHarness. State lives only
+ * for the lifetime of the Map (i.e., this harness instance). Durable backends
+ * must be supplied explicitly by the caller.
+ */
+export function createInMemoryStorage() {
+    const store = new Map();
+    return {
+        async get(key) {
+            const val = store.get(key);
+            if (val === undefined) {
+                return null;
+            }
+            return frameworkCast(val);
+        },
+        async set(key, value) {
+            store.set(key, value);
+        },
+        async delete(key) {
+            store.delete(key);
+        },
+        async list(prefix) {
+            return [
+                ...store.keys(),
+            ].filter((k) => k.startsWith(prefix));
+        },
+    };
+}
+//#endregion

package/dist/runtime/item-log-impl.d.ts

@@ -0,0 +1,11 @@
+import type { ItemSchemaRegistry } from '../schemas/item';
+import type { ItemLog } from '../types/context';
+import type { Item } from '../types/items';
+export declare class ItemLogImpl implements ItemLog {
+    private readonly itemSchemas;
+    private readonly _items;
+    private _frozenCache;
+    constructor(itemSchemas?: ItemSchemaRegistry);
+    get items(): ReadonlyArray<Item>;
+    append(item: Item): void;
+}

package/dist/runtime/item-log-impl.js

@@ -0,0 +1,25 @@
+import { defaultItemSchemaRegistry } from '../schemas/item';
+export class ItemLogImpl {
+    itemSchemas;
+    _items = [];
+    _frozenCache = null;
+    constructor(itemSchemas = defaultItemSchemaRegistry) {
+        this.itemSchemas = itemSchemas;
+    }
+    get items() {
+        if (!this._frozenCache) {
+            this._frozenCache = Object.freeze([
+                ...this._items,
+            ]);
+        }
+        const frozenItems = this._frozenCache;
+        if (!frozenItems) {
+            return [];
+        }
+        return frozenItems;
+    }
+    append(item) {
+        this._items.push(this.itemSchemas.parse(item));
+        this._frozenCache = null;
+    }
+}

package/dist/runtime/message-queue.d.ts

@@ -0,0 +1,30 @@
+import type { ExecuteInput } from '../types/items';
+import type { DeliveryMode, ExecuteOptions } from '../types/runtime';
+/** @internal A message accepted by `AgentHarness.execute()` and held until the
+ *  session runner processes it. The effective `DeliveryMode` is resolved at
+ *  enqueue time so the runner never has to look at harness defaults again. */
+export interface QueuedMessage {
+    readonly id: string;
+    readonly input: ExecuteInput;
+    readonly deliveryMode: DeliveryMode;
+    readonly options: ExecuteOptions;
+    readonly enqueuedAt: number;
+}
+/** @internal Subscription callback fired after any mutation. */
+export type QueueChangeListener = (size: number) => void;
+/** @internal Per-thread FIFO of inbox messages with prepend + subscription.
+ *
+ *  `prepend` is used when an in-flight turn is aborted — the aborting message
+ *  is re-inserted at the head so the runner picks it up before any messages
+ *  that arrived after the abort. */
+export declare class MessageQueue {
+    private readonly items;
+    private readonly listeners;
+    enqueue(message: QueuedMessage): void;
+    prepend(message: QueuedMessage): void;
+    drainAll(): QueuedMessage[];
+    peekAll(): ReadonlyArray<QueuedMessage>;
+    get size(): number;
+    subscribe(listener: QueueChangeListener): () => void;
+    private notify;
+}

package/dist/runtime/message-queue.js

@@ -0,0 +1,46 @@
+//#endregion
+//#region MessageQueue
+/** @internal Per-thread FIFO of inbox messages with prepend + subscription.
+ *
+ *  `prepend` is used when an in-flight turn is aborted — the aborting message
+ *  is re-inserted at the head so the runner picks it up before any messages
+ *  that arrived after the abort. */
+export class MessageQueue {
+    items = [];
+    listeners = new Set();
+    enqueue(message) {
+        this.items.push(message);
+        this.notify();
+    }
+    prepend(message) {
+        this.items.unshift(message);
+        this.notify();
+    }
+    drainAll() {
+        if (this.items.length === 0) {
+            return [];
+        }
+        const drained = this.items.splice(0, this.items.length);
+        this.notify();
+        return drained;
+    }
+    peekAll() {
+        return this.items;
+    }
+    get size() {
+        return this.items.length;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    notify() {
+        const size = this.items.length;
+        for (const listener of this.listeners) {
+            listener(size);
+        }
+    }
+}
+//#endregion

package/dist/runtime/session-runner.d.ts

@@ -0,0 +1,77 @@
+import type { Context } from '../types/context';
+import type { HarnessResponse } from '../types/harness-result';
+import type { Item } from '../types/items';
+import type { HarnessStatus } from '../types/runtime';
+import { EventBroadcaster } from './event-broadcaster';
+import type { QueuedMessage } from './message-queue';
+import { MessageQueue } from './message-queue';
+/** @internal Callback the harness supplies to run a single turn against a
+ *  prepared context. The runner invokes this once per turn; it returns the
+ *  final text as a string and must append any produced items to `ctx.itemLog`. */
+export type RunTurnFn = (ctx: Context, turn: TurnContext, signal: AbortSignal) => Promise<string>;
+/** @internal Everything the harness needs to stamp the current turn. */
+export interface TurnContext {
+    readonly turnId: string;
+    readonly session: SessionRunner;
+}
+/** @internal Callback the harness supplies to build a fresh context for a
+ *  single turn. Receives the already-converted items to seed the context
+ *  (so the runner is the single point of ExecuteInput → Item[] conversion),
+ *  plus the messages being delivered this turn so the harness can honour
+ *  per-turn `ExecuteOptions` (the first message's options establish
+ *  resourceId/state/memory for the turn). */
+export type CreateContextFn = (items: ReadonlyArray<Item>, turnId: string, messages: ReadonlyArray<QueuedMessage>) => Context;
+export interface SessionRunnerOpts {
+    readonly threadId: string;
+    readonly agentName: string;
+    readonly runTurn: RunTurnFn;
+    readonly createContext: CreateContextFn;
+}
+/**
+ * @internal
+ *
+ * Per-thread runner. Drains the MessageQueue and drives turns on the shared
+ * session broadcaster. Emits `turn_started` / `turn_completed` /
+ * `inbox_injected` framework events so consumers can correlate queued
+ * messages with the turn that delivered them.
+ *
+ * Abort semantics: when `abort()` is called, the current AbortController is
+ * fired (cancelling the in-flight LLM call) and a flag is set so the runner
+ * does NOT auto-restart from the queue until the caller re-kicks. For the
+ * ESC-restart UX, callers typically enqueue the new message first, then
+ * abort — the new message is the head of the queue when the runner wakes.
+ */
+export declare class SessionRunner {
+    readonly threadId: string;
+    readonly broadcaster: EventBroadcaster;
+    readonly queue: MessageQueue;
+    private readonly agentName;
+    private readonly runTurn;
+    private readonly createContext;
+    private status;
+    private currentController?;
+    private currentCtx?;
+    private loopPromise?;
+    private lastResponse?;
+    private lastError?;
+    private readonly responseWaiters;
+    constructor(opts: SessionRunnerOpts);
+    getStatus(): HarnessStatus;
+    /** Resolves once the queue has been drained and the runner is idle with a
+     *  response available. If nothing has run yet, waits for the first turn.
+     *
+     *  The cached `lastError` is only surfaced when the session is genuinely
+     *  idle with no pending work. If a new turn is running or a message is
+     *  queued, the caller is asking about the NEXT response — we must wait
+     *  for that turn rather than reject with the stale error. */
+    getAgentResponse(): Promise<HarnessResponse>;
+    /** Cancel the in-flight turn. Does NOT re-kick — callers that want restart
+     *  behaviour should enqueue a message before/after calling abort. */
+    abort(reason?: string): Promise<void>;
+    /** Start the drain loop if not already running. Safe to call many times. */
+    kick(): void;
+    private drain;
+    private runOneTurn;
+    private resolveWaiters;
+    private rejectWaiters;
+}