@noetic-tools/core 0.0.1 → 0.1.0

package/dist/interpreter/execute-every.js

@@ -1,143 +0,0 @@
-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

@@ -1,3 +0,0 @@
-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

@@ -1,215 +0,0 @@
-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

@@ -1,4 +0,0 @@
-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>;

package/dist/interpreter/execute-llm.js

@@ -1,217 +0,0 @@
-import { ZodError } from 'zod';
-import { NoeticErrorImpl } from '../errors/noetic-error';
-import { resolveLayerTools } from '../memory/layer-api';
-import { commitLayerUsage, computeLayerUsage } from '../memory/layer-usage';
-import { assembleView } from '../memory/projector';
-import { SteeringAction } from '../types/steering';
-import { frameworkCast } from './framework-cast';
-import { createMessage, extractAssistantText, trackUsage } from './message-helpers';
-import { isFunctionCall, isMutableContext } from './typeguards';
-const MAX_STEERING_RETRIES = 3;
-const emptyRecall = [];
-/**
- * Resolves which tools to send and what restrictions to apply.
- *
- * When a unified tool set exists on the context (collected before execution),
- * every LLM call sends the full set and step.tools narrows via allowedToolNames.
- *
- * Semantics:
- *   step.tools = undefined → unrestricted (all tools, no allowedToolNames)
- *   step.tools = []        → no tools at all
- *   step.tools = [a, b]    → full set sent, restrict to a and b
- *
- * Fallback: when no unified set exists (e.g. harness.run() called directly),
- * merge step tools with layer tools as before.
- */
-function resolveToolsAndRestrictions(step, layers, ctx) {
-    // step.tools = [] → explicit opt-out
-    if (step.tools && step.tools.length === 0) {
-        return {
-            tools: undefined,
-            allowedToolNames: undefined,
-        };
-    }
-    const unified = ctx.unifiedTools;
-    if (unified && unified.length > 0) {
-        const allowedToolNames = step.tools ? step.tools.map((t) => t.name) : undefined;
-        return {
-            tools: [
-                ...unified,
-            ],
-            allowedToolNames,
-        };
-    }
-    // Fallback: no unified set (direct harness.run() path)
-    const layerTools = layers && layers.length > 0 ? resolveLayerTools(layers, ctx.harness, ctx) : [];
-    if (layerTools.length === 0 && !step.tools) {
-        return {
-            tools: undefined,
-            allowedToolNames: undefined,
-        };
-    }
-    const merged = [
-        ...(step.tools ?? []),
-        ...layerTools,
-    ];
-    return {
-        tools: merged.length > 0 ? merged : undefined,
-        allowedToolNames: undefined,
-    };
-}
-async function runInputPipeline({ ctx, layers, input }) {
-    const userItem = createMessage(input, 'user');
-    const { items: finalItems } = await ctx.harness.runAppendPipeline(layers, [
-        userItem,
-    ], ctx);
-    for (const item of finalItems) {
-        ctx.itemLog.append(item);
-    }
-}
-//#endregion
-export async function executeLLM(step, input, ctx, layers) {
-    const baseCtx = frameworkCast(ctx);
-    const hasLayers = layers !== undefined && layers.length > 0;
-    // Append user input — through layer pipeline if layers exist, otherwise direct.
-    if (typeof input === 'string' && input.length > 0) {
-        if (hasLayers) {
-            await runInputPipeline({
-                ctx: baseCtx,
-                layers,
-                input,
-            });
-        }
-        else {
-            baseCtx.itemLog.append(createMessage(input, 'user'));
-        }
-    }
-    const { tools: resolvedTools, allowedToolNames } = resolveToolsAndRestrictions(step, layers, baseCtx);
-    // Recall once per LLM step: every layer with a recall hook contributes its
-    // current view. Results drive both the assembled context window and the
-    // per-layer usage breakdown (ctx.lastLayerUsage). Recall fires before the
-    // steering retry loop because retries replay the same context.
-    const recallQuery = typeof input === 'string' ? input : '';
-    const recallResults = hasLayers
-        ? await baseCtx.harness.recallLayers(layers, recallQuery, baseCtx)
-        : emptyRecall;
-    const layerOutputItems = recallResults.flatMap((r) => r.items);
-    let retries = 0;
-    while (retries <= MAX_STEERING_RETRIES) {
-        const rawHistoryItems = baseCtx.itemLog.items;
-        const projectedHistoryItems = hasLayers
-            ? await baseCtx.harness.projectHistory(layers, rawHistoryItems, baseCtx)
-            : rawHistoryItems;
-        const assembledItems = layerOutputItems.length > 0
-            ? assembleView({
-                systemPromptItems: [],
-                layerOutputItems,
-                historyItems: [
-                    ...projectedHistoryItems,
-                ],
-            })
-            : projectedHistoryItems === rawHistoryItems
-                ? rawHistoryItems
-                : [
-                    ...projectedHistoryItems,
-                ];
-        const request = resolvedTools
-            ? {
-                model: step.model,
-                items: assembledItems,
-                instructions: step.instructions,
-                tools: resolvedTools,
-                params: step.params,
-                outputSchema: step.output,
-                emit: step.emit,
-                ctx: baseCtx,
-                layers,
-                allowedToolNames,
-            }
-            : {
-                model: step.model,
-                items: assembledItems,
-                instructions: step.instructions,
-                params: step.params,
-                outputSchema: step.output,
-                emit: step.emit,
-            };
-        const response = await baseCtx.harness.callModel(request);
-        if (hasLayers) {
-            const decision = await baseCtx.harness.afterModelCall(layers, response, baseCtx);
-            if (decision.action === SteeringAction.Deny) {
-                throw new NoeticErrorImpl({
-                    kind: 'steering_denied',
-                    guidance: decision.guidance,
-                });
-            }
-            if (decision.action === SteeringAction.Guide && retries < MAX_STEERING_RETRIES) {
-                baseCtx.itemLog.append(createMessage(decision.guidance ?? 'Please adjust your response.', 'developer'));
-                retries++;
-                continue;
-            }
-        }
-        const toolCalls = [];
-        for (const item of response.items) {
-            baseCtx.itemLog.append(item);
-            if (isFunctionCall(item)) {
-                toolCalls.push(item);
-            }
-        }
-        const meta = {
-            toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
-            usage: response.usage,
-            cost: response.cost,
-            responseItems: response.items,
-        };
-        if (isMutableContext(baseCtx)) {
-            baseCtx.lastStepMeta = meta;
-        }
-        trackUsage(baseCtx, response);
-        commitLayerUsage(baseCtx, computeLayerUsage({
-            ctx: baseCtx,
-            modelId: step.model,
-            instructions: step.instructions,
-            tools: resolvedTools,
-            recallResults,
-        }));
-        if (hasLayers) {
-            await baseCtx.harness.storeLayers(layers, response, baseCtx);
-        }
-        const lastText = extractAssistantText(response.items);
-        if (step.output) {
-            try {
-                const parsed = JSON.parse(lastText);
-                return step.output.parse(parsed);
-            }
-            catch (e) {
-                if (e instanceof SyntaxError || e instanceof ZodError) {
-                    throw new NoeticErrorImpl({
-                        kind: 'llm_parse_error',
-                        stepId: step.id,
-                        raw: lastText,
-                        schema: step.output,
-                        zodError: e instanceof ZodError
-                            ? e
-                            : new ZodError([
-                                {
-                                    code: 'custom',
-                                    message: `Invalid JSON: ${e.message}`,
-                                    path: [],
-                                },
-                            ]),
-                    });
-                }
-                throw e;
-            }
-        }
-        return frameworkCast(lastText);
-    }
-    // Safety net: the loop above always returns or throws within the body.
-    // This throw is unreachable but protects against future refactors that
-    // might break the loop invariant.
-    throw new NoeticErrorImpl({
-        kind: 'step_failed',
-        stepId: step.id,
-        cause: new Error('Steering retries exhausted'),
-        retriesExhausted: true,
-    });
-}

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

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