@noetic-tools/core 0.0.1

package/dist/index.js

@@ -0,0 +1,112 @@
+//#region Adapters
+/** @public */
+export { createInMemoryFsAdapter } from './adapters/in-memory-fs-adapter';
+/** @public */
+export { createInMemoryShellAdapter } from './adapters/in-memory-shell-adapter';
+/** @public */
+export { createInMemorySubprocessAdapter } from './adapters/in-memory-subprocess-adapter';
+/** @public */
+export { createLocalFsAdapter } from './adapters/local-fs-adapter';
+/** @public */
+export { createLocalShellAdapter, } from './adapters/local-shell-adapter';
+/** @public */
+export { createLocalSubprocessAdapter, defaultProcessSignaller, } from './adapters/local-subprocess-adapter';
+/** @public */
+export { createOpenRouterEmbed } from './adapters/openrouter';
+//#endregion
+//#region Builders
+/** @public */
+export { channel } from './builders/channel-builder';
+/** @public */
+export { branch, fork } from './builders/control-flow-builders';
+/** @public */
+export { every } from './builders/every';
+/** @public */
+export { layerData, layerFn } from './builders/layer-provides-builders';
+/** @public */
+export { loop } from './builders/loop-builder';
+/** @public */
+export { memory } from './builders/memory-builder';
+/** @public */
+export { provide } from './builders/provide-builder';
+/** @public */
+export { spawn } from './builders/spawn-builder';
+/** @public */
+export { step } from './builders/step-builders';
+/** @public */
+export { tool, toolWithGenerator } from './builders/tool-builder';
+/** @public */
+export { aiCondition, allCondition, anyCondition, cosineSimilarity, embeddingMatch, otherwise, semanticRoute, semanticSwitch, when, } from './conditions';
+//#endregion
+//#region Errors
+/** @public */
+export { isNoeticConfigError, NoeticConfigError } from './errors/noetic-config-error';
+/** @public */
+export { isNoeticError, NoeticErrorImpl } from './errors/noetic-error';
+//#endregion
+//#region Execution
+/** @public */
+export { execute } from './interpreter/execute';
+/** @public */
+export { durableTaskState } from './memory/layers/durable-task-state';
+/** @public */
+export { fileReference } from './memory/layers/file-reference';
+/** @public */
+export { historyWindow } from './memory/layers/history-window';
+/** @public */
+export { observationalMemory } from './memory/layers/observational-memory';
+/** @public */
+export { PlanPhase, planMemory } from './memory/layers/plan';
+/** @public */
+export { staticContent } from './memory/layers/static-content';
+/** @public */
+export { steering } from './memory/layers/steering';
+/** @public */
+export { toolMemoryLayer } from './memory/layers/tool-memory-layer';
+/** @public */
+export { workingMemory } from './memory/layers/working-memory';
+/** @public */
+export { stripUnresolvedToolCalls } from './memory/strip-unresolved';
+//#endregion
+//#region Observability
+/** @public */
+export { InMemoryExporter, NoopExporter } from './observability/trace-exporter';
+/** @public */
+export { createInMemoryStorage } from './runtime/in-memory-storage';
+/** @public */
+export { FlowSchema, flowDepth, validateFlow, walkFlow } from './patterns/flow';
+/** @public */
+export { interview } from './patterns/interview';
+/** @public */
+export { adaptivePlan, compilePlan, PlanNodeSchema } from './patterns/plans';
+/** @public */
+export { ralphWiggum } from './patterns/ralph-wiggum';
+/** @public */
+export { react } from './patterns/react';
+//#endregion
+//#region Runtime
+/** @public */
+export { AgentHarness } from './runtime/agent-harness';
+//#endregion
+//#region Schemas
+/** @public */
+export { defaultItemSchemaRegistry, ItemSchema, ItemSchemaRegistry } from './schemas/item';
+//#endregion
+//#region Types — Context
+/** @public */
+export { getToolCwd, setToolCwd, snapshotCwdState } from './runtime/cwd-helpers';
+/** @public */
+export { DetachedStatus } from './types/detached';
+/** @public */
+export { Slot } from './types/memory';
+/** @public */
+export { LedgerEntryKind, SteeringAction } from './types/steering';
+/** @public */
+export { TIMEOUT_ERROR_PREFIX } from './types/shell-adapter';
+//#endregion
+//#region Until
+/** @public */
+export { all, any } from './until/combinators';
+/** @public */
+export { until } from './until/predicates';
+//#endregion

package/dist/internal-test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @internal
+ * Test-only exports for cross-package testing.
+ *
+ * These are implementation classes that tests need to construct mock instances.
+ * Application code should NEVER import from this path.
+ */
+export { SpanImpl } from './observability/span-impl';
+export { ChannelStore } from './runtime/channel-store';
+export { ContextImpl } from './runtime/context-impl';
+export { ItemLogImpl } from './runtime/item-log-impl';

package/dist/internal-test.js

@@ -0,0 +1,11 @@
+/**
+ * @internal
+ * Test-only exports for cross-package testing.
+ *
+ * These are implementation classes that tests need to construct mock instances.
+ * Application code should NEVER import from this path.
+ */
+export { SpanImpl } from './observability/span-impl';
+export { ChannelStore } from './runtime/channel-store';
+export { ContextImpl } from './runtime/context-impl';
+export { ItemLogImpl } from './runtime/item-log-impl';

package/dist/interpreter/clone-guard.d.ts

@@ -0,0 +1,4 @@
+export declare function cloneWithGuard<T>(value: T, label: string, opts?: {
+    warnBytes?: number;
+    maxBytes?: number;
+}): T;

package/dist/interpreter/clone-guard.js

@@ -0,0 +1,18 @@
+const DEFAULT_WARN_BYTES = 10 * 1024 * 1024; // 10MB
+function estimateSize(value) {
+    try {
+        return JSON.stringify(value)?.length ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
+export function cloneWithGuard(value, label, opts) {
+    const warnBytes = opts?.warnBytes ?? DEFAULT_WARN_BYTES;
+    const size = estimateSize(value);
+    if (size > warnBytes) {
+        console.warn(`[noetic] ${label}: state size (~${Math.round(size / 1024 / 1024)}MB) exceeds ${Math.round(warnBytes / 1024 / 1024)}MB threshold. ` +
+            'Consider reducing state size to avoid performance issues.');
+    }
+    return structuredClone(value);
+}

package/dist/interpreter/collect-tools.d.ts

@@ -0,0 +1,12 @@
+import type { Tool } from '../types/common';
+import type { Step } from '../types/step';
+/**
+ * Recursively walks a step tree and collects all Tool instances
+ * declared on LLM steps. Used to build the unified tool set
+ * that gets sent with every LLM call for prompt cache efficiency.
+ */
+export declare function collectAllTools<TMemory = unknown, I = unknown, O = unknown>(step: Step<TMemory, I, O>): Tool[];
+/**
+ * Deduplicates tools by name, keeping the first occurrence.
+ */
+export declare function deduplicateTools(tools: ReadonlyArray<Tool>): Tool[];

package/dist/interpreter/collect-tools.js

@@ -0,0 +1,70 @@
+import { frameworkCast } from './framework-cast';
+/**
+ * Recursively walks a step tree and collects all Tool instances
+ * declared on LLM steps. Used to build the unified tool set
+ * that gets sent with every LLM call for prompt cache efficiency.
+ */
+export function collectAllTools(step) {
+    const tools = [];
+    // walkStep uses Step with defaults (unknown generics); the cast is safe because
+    // we only read the `.tools`, `.child`, `.steps`, `._optimizable` structural fields.
+    walkStep(frameworkCast(step), tools);
+    return deduplicateTools(tools);
+}
+/**
+ * Deduplicates tools by name, keeping the first occurrence.
+ */
+export function deduplicateTools(tools) {
+    const seen = new Map();
+    for (const tool of tools) {
+        if (!seen.has(tool.name)) {
+            seen.set(tool.name, tool);
+        }
+    }
+    return [
+        ...seen.values(),
+    ];
+}
+function walkStep(step, out) {
+    switch (step.kind) {
+        case 'llm':
+            if (step.tools) {
+                out.push(...step.tools);
+            }
+            return;
+        case 'run':
+        case 'tool':
+            return;
+        case 'branch':
+            if (step._optimizable) {
+                for (const child of step._optimizable) {
+                    walkStep(child, out);
+                }
+            }
+            return;
+        case 'fork':
+            if (step._optimizable) {
+                for (const child of step._optimizable) {
+                    walkStep(child, out);
+                }
+            }
+            return;
+        case 'provide':
+            walkStep(step.child, out);
+            return;
+        case 'spawn':
+            walkStep(step.child, out);
+            return;
+        case 'loop':
+            for (const child of step.steps) {
+                walkStep(child, out);
+            }
+            return;
+        case 'every':
+            walkStep(step.step, out);
+            return;
+        default:
+            step;
+            return;
+    }
+}

package/dist/interpreter/execute-branch.d.ts

@@ -0,0 +1,3 @@
+import type { Context } from '../types/context';
+import type { ExecuteStepFn, StepBranch } from '../types/step';
+export declare function executeBranch<TMemory, I, O>(step: StepBranch<TMemory, I, O>, input: I, ctx: Context<TMemory>, executeStep: ExecuteStepFn): Promise<O>;

package/dist/interpreter/execute-branch.js

@@ -0,0 +1,10 @@
+import { frameworkCast } from './framework-cast';
+export async function executeBranch(step, input, ctx, executeStep) {
+    const selected = await step.route(input, ctx);
+    if (selected === null) {
+        // Requires I assignable to O for null route — when no branch is selected,
+        // the input passes through. Callers must ensure I is compatible with O.
+        return frameworkCast(input);
+    }
+    return executeStep(selected, input, ctx);
+}

package/dist/interpreter/execute-every.d.ts

@@ -0,0 +1,15 @@
+import type { Context } from '../types/context';
+import type { ExecuteStepFn, StepEvery } from '../types/step';
+/**
+ * Executes an `every` step: runs the body step forever, paced by `ms ± jitter`,
+ * woken early by `wakeOn`. Throws `cancelled` when the context is aborted.
+ *
+ * On body throw, behavior depends on `onError`:
+ * - `'continue'` (default): emit `every.iteration.error` span event and proceed
+ *   to the park step as if no error occurred.
+ * - `'fail'`: re-throw, terminating the operator.
+ *
+ * The body's output is discarded — `every` runs forever and does not accumulate
+ * iteration outputs. Only ever returns by throwing on cancellation or `fail`.
+ */
+export declare function executeEvery<TMemory, I, O>(step: StepEvery<TMemory, I, O>, input: I, ctx: Context<TMemory>, executeStep: ExecuteStepFn): Promise<O>;

package/dist/interpreter/execute-every.js

@@ -0,0 +1,143 @@
+import { isNoeticError, NoeticErrorImpl } from '../errors/noetic-error';
+import { getContextChannelStore } from './typeguards';
+//#endregion
+//#region Helper Functions
+/** Returns the next park duration in ms, applying random jitter clamped to `[ms - jitter, ms + jitter]`. */
+function nextParkMs(ms, jitter) {
+    if (jitter <= 0) {
+        return ms;
+    }
+    // Math.random() returns [0, 1); shift to [-1, 1) so jitter is symmetric.
+    const offset = (Math.random() * 2 - 1) * jitter;
+    const value = ms + offset;
+    if (value < 0) {
+        return 0;
+    }
+    return value;
+}
+/**
+ * Parks for `ms` ms, returning early if `wakeOn` receives a message or the
+ * context is aborted. Always resolves; never throws (cancellation surfaces on
+ * the next iteration's abort check).
+ */
+function park(parkCtx) {
+    const duration = nextParkMs(parkCtx.ms, parkCtx.jitter);
+    return new Promise((resolve) => {
+        let settled = false;
+        let timer = null;
+        let abortPoll = null;
+        let wakeUnsub = null;
+        const settle = () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (timer !== null) {
+                clearTimeout(timer);
+            }
+            if (abortPoll !== null) {
+                clearInterval(abortPoll);
+            }
+            if (wakeUnsub !== null) {
+                wakeUnsub();
+            }
+            resolve();
+        };
+        timer = setTimeout(settle, duration);
+        // Poll the abort flag at a coarse interval to wake parking when the
+        // context is aborted. The Context interface exposes only `aborted` as a
+        // boolean, so this is the simplest interruption strategy that respects
+        // the public contract.
+        abortPoll = setInterval(() => {
+            if (parkCtx.ctx.aborted) {
+                settle();
+            }
+        }, 5);
+        if (!parkCtx.wakeOn) {
+            return;
+        }
+        const { channelStore } = parkCtx;
+        if (channelStore) {
+            // Non-consuming subscription so the body still observes the message that
+            // woke us — `recv()` would dequeue queue-mode messages and leave the
+            // body's drain loop empty.
+            wakeUnsub = channelStore.subscribeWake(parkCtx.wakeOn, settle);
+            return;
+        }
+        // Contexts without a ContextImpl/channel store have no body draining the
+        // channel anyway; the destructive `recv` is acceptable in that edge case.
+        parkCtx.ctx
+            .recv(parkCtx.wakeOn, {
+            timeout: Math.max(duration, 1) + 1e2,
+        })
+            .then(settle)
+            .catch(() => {
+            // Channel timeout / store error — another path settles us.
+        });
+    });
+}
+function recordIterationError(ctx, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error && error.stack ? error.stack : '';
+    ctx.span.addEvent('every.iteration.error', {
+        message,
+        stack,
+    });
+}
+function throwCancelled(reason) {
+    throw new NoeticErrorImpl({
+        kind: 'cancelled',
+        reason: reason ?? 'context aborted',
+    });
+}
+//#endregion
+//#region Public API
+/**
+ * Executes an `every` step: runs the body step forever, paced by `ms ± jitter`,
+ * woken early by `wakeOn`. Throws `cancelled` when the context is aborted.
+ *
+ * On body throw, behavior depends on `onError`:
+ * - `'continue'` (default): emit `every.iteration.error` span event and proceed
+ *   to the park step as if no error occurred.
+ * - `'fail'`: re-throw, terminating the operator.
+ *
+ * The body's output is discarded — `every` runs forever and does not accumulate
+ * iteration outputs. Only ever returns by throwing on cancellation or `fail`.
+ */
+export async function executeEvery(step, input, ctx, executeStep) {
+    const onError = step.onError ?? 'continue';
+    const jitter = step.jitter ?? 0;
+    // Resolve once — the channel store reference is stable for the lifetime
+    // of the every loop, no need to re-derive it per park.
+    const channelStore = getContextChannelStore(ctx);
+    while (true) {
+        if (ctx.aborted) {
+            throwCancelled(ctx.abortReason);
+        }
+        try {
+            await executeStep(step.step, input, ctx);
+        }
+        catch (e) {
+            if (onError === 'fail') {
+                throw e;
+            }
+            // 'continue' policy — but a cancellation should still terminate the
+            // operator promptly rather than be swallowed and re-parked.
+            if (isNoeticError(e) && e.noeticError.kind === 'cancelled') {
+                throw e;
+            }
+            recordIterationError(ctx, e);
+        }
+        if (ctx.aborted) {
+            throwCancelled(ctx.abortReason);
+        }
+        await park({
+            ms: step.ms,
+            jitter,
+            wakeOn: step.wakeOn,
+            ctx,
+            channelStore,
+        });
+    }
+}
+//#endregion

package/dist/interpreter/execute-fork.d.ts

@@ -0,0 +1,3 @@
+import type { Context } from '../types/context';
+import type { ExecuteStepFn, StepFork } from '../types/step';
+export declare function executeFork<TMemory, I, O>(step: StepFork<TMemory, I, O>, input: I, ctx: Context<TMemory>, executeStep: ExecuteStepFn): Promise<O>;

package/dist/interpreter/execute-fork.js

@@ -0,0 +1,215 @@
+import { isNoeticError, NoeticErrorImpl } from '../errors/noetic-error';
+import { ContextImpl } from '../runtime/context-impl';
+import { snapshotCwdState } from '../runtime/cwd-helpers';
+import { cloneWithGuard } from './clone-guard';
+import { frameworkCast } from './framework-cast';
+import { getContextChannelStore, isContextImpl } from './typeguards';
+function createChildContexts(ctx, count, stepId) {
+    const threadId = isContextImpl(ctx) ? ctx.threadId : crypto.randomUUID();
+    const resourceId = isContextImpl(ctx) ? ctx.resourceId : undefined;
+    const channelStore = getContextChannelStore(ctx);
+    return Array.from({
+        length: count,
+    }, () => new ContextImpl({
+        harness: ctx.harness,
+        parent: ctx,
+        items: [
+            ...ctx.itemLog.items,
+        ],
+        state: cloneWithGuard(ctx.state, `Fork '${stepId}'`),
+        threadId,
+        resourceId,
+        channelStore,
+        cwdState: snapshotCwdState(ctx),
+    }));
+}
+export async function executeFork(step, input, ctx, executeStep) {
+    const baseCtx = frameworkCast(ctx);
+    const paths = step.paths(input, ctx);
+    if (paths.length === 0) {
+        if (step.mode === 'all') {
+            return step.merge([], ctx);
+        }
+        if (step.mode === 'settle') {
+            return step.merge([], ctx);
+        }
+        throw new NoeticErrorImpl({
+            kind: 'fork_partial',
+            stepId: step.id,
+            succeeded: [],
+            failed: [],
+        });
+    }
+    const childContexts = createChildContexts(baseCtx, paths.length, step.id);
+    const concurrency = step.concurrency ?? paths.length;
+    switch (step.mode) {
+        case 'all':
+            return executeAll(step, paths, input, ctx, childContexts, executeStep, concurrency);
+        case 'race':
+            return executeRace(step, paths, input, ctx, childContexts, executeStep, concurrency);
+        case 'settle':
+            return executeSettle(step, paths, input, ctx, childContexts, executeStep, concurrency);
+        default: {
+            const _exhaustive = step;
+            throw new NoeticErrorImpl({
+                kind: 'step_failed',
+                stepId: 'unknown',
+                cause: new Error('Unknown fork mode'),
+                retriesExhausted: false,
+            });
+        }
+    }
+}
+async function runWithConcurrency(tasks, concurrency) {
+    const results = new Array(tasks.length);
+    let nextIndex = 0;
+    async function runNext() {
+        while (nextIndex < tasks.length) {
+            const index = nextIndex++;
+            try {
+                const value = await tasks[index]();
+                results[index] = {
+                    status: 'fulfilled',
+                    value,
+                };
+            }
+            catch (reason) {
+                results[index] = {
+                    status: 'rejected',
+                    reason,
+                };
+            }
+        }
+    }
+    const workers = Array.from({
+        length: Math.min(concurrency, tasks.length),
+    }, () => runNext());
+    await Promise.all(workers);
+    return results;
+}
+function toNoeticError(err, stepId) {
+    if (isNoeticError(err)) {
+        return err.noeticError;
+    }
+    return {
+        kind: 'step_failed',
+        stepId,
+        cause: err instanceof Error ? err : new Error(String(err)),
+        retriesExhausted: false,
+    };
+}
+function classifyResults(settled, paths) {
+    const succeeded = [];
+    const failed = [];
+    settled.forEach((result, i) => {
+        if (result.status === 'fulfilled') {
+            succeeded.push({
+                stepId: paths[i].id,
+                value: result.value,
+            });
+        }
+        else {
+            failed.push({
+                stepId: paths[i].id,
+                error: toNoeticError(result.reason, paths[i].id),
+            });
+        }
+    });
+    return {
+        succeeded,
+        failed,
+    };
+}
+async function executeAll(step, paths, _input, ctx, childContexts, executeStep, concurrency) {
+    const tasks = paths.map((path, i) => () => executeStep(path, _input, frameworkCast(childContexts[i])));
+    const settled = await runWithConcurrency(tasks, concurrency);
+    const { succeeded, failed } = classifyResults(settled, paths);
+    if (failed.length > 0) {
+        throw new NoeticErrorImpl({
+            kind: 'fork_partial',
+            stepId: step.id,
+            succeeded,
+            failed,
+        });
+    }
+    const results = succeeded.map((s) => s.value);
+    return step.merge(results, ctx);
+}
+async function executeRace(step, paths, input, ctx, childContexts, executeStep, concurrency) {
+    const raceBaseCtx = frameworkCast(ctx);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let failedCount = 0;
+        let nextIndex = 0;
+        const errors = [];
+        const totalPaths = paths.length;
+        function startNext() {
+            if (settled || nextIndex >= totalPaths) {
+                return;
+            }
+            const i = nextIndex++;
+            executeStep(paths[i], input, frameworkCast(childContexts[i]))
+                .then((result) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                // Winner's state replaces parent's
+                if (isContextImpl(raceBaseCtx)) {
+                    raceBaseCtx.state = childContexts[i].state;
+                }
+                // Resolve first, then abort losers (non-critical path)
+                resolve(result);
+                for (let j = 0; j < childContexts.length; j++) {
+                    if (j !== i) {
+                        childContexts[j].abort('race lost');
+                    }
+                }
+            })
+                .catch((err) => {
+                failedCount++;
+                errors.push({
+                    stepId: paths[i].id,
+                    error: toNoeticError(err, paths[i].id),
+                });
+                // Start next task if available
+                if (!settled) {
+                    startNext();
+                }
+                if (failedCount === totalPaths && !settled) {
+                    settled = true;
+                    reject(new NoeticErrorImpl({
+                        kind: 'fork_partial',
+                        stepId: step.id,
+                        succeeded: [],
+                        failed: errors,
+                    }));
+                }
+            });
+        }
+        // Launch initial batch respecting concurrency
+        const initialBatch = Math.min(concurrency, totalPaths);
+        for (let i = 0; i < initialBatch; i++) {
+            startNext();
+        }
+    });
+}
+async function executeSettle(step, paths, input, _ctx, childContexts, executeStep, concurrency) {
+    const tasks = paths.map((path, i) => () => executeStep(path, input, frameworkCast(childContexts[i])));
+    const settled = await runWithConcurrency(tasks, concurrency);
+    const results = settled.map((result, i) => {
+        if (result.status === 'fulfilled') {
+            return {
+                stepId: paths[i].id,
+                status: 'fulfilled',
+                value: result.value,
+            };
+        }
+        return {
+            stepId: paths[i].id,
+            status: 'rejected',
+            error: toNoeticError(result.reason, paths[i].id),
+        };
+    });
+    return step.merge(results, _ctx);
+}

package/dist/interpreter/execute-llm.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from '../types/context';
+import type { MemoryLayer } from '../types/memory';
+import type { StepLLM } from '../types/step';
+export declare function executeLLM<TMemory, I, O>(step: StepLLM<TMemory, I, O>, input: I, ctx: Context<TMemory>, layers?: MemoryLayer[]): Promise<O>;