@noetic-tools/core 0.0.1 → 0.1.1

package/dist/interpreter/execute-control.js

@@ -0,0 +1,530 @@
+/**
+ * Control-flow step handlers: branch, fork, loop, every.
+ */
+import { isNoeticError, NoeticErrorImpl } from '../errors/noetic-error.js';
+import { ContextImpl } from '../runtime/context-impl.js';
+import { snapshotCwdState } from '../runtime/cwd-helpers.js';
+import { frameworkCast } from '../util/framework-cast.js';
+import { createMessage } from '../util/message-helpers.js';
+import { cloneWithGuard } from './clone-guard.js';
+import { getContextChannelStore, isContextImpl, isMutableContext } from './typeguards.js';
+//#region branch
+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);
+}
+//#endregion
+//#region fork
+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);
+}
+function hasTextField(value) {
+    return typeof value === 'object' && value !== null && 'text' in value;
+}
+async function recvInboxWithTimeout(ctx, step) {
+    if (!step.inbox) {
+        return null;
+    }
+    if ((step.parkTimeout ?? 0) <= 0) {
+        return ctx.tryRecv(step.inbox);
+    }
+    try {
+        return await ctx.recv(step.inbox, {
+            timeout: step.parkTimeout,
+        });
+    }
+    catch {
+        // Expected: channel_timeout error when parkTimeout expires with no message.
+        return null;
+    }
+}
+function prepareNextInput(step, lastOutput, verdict, ctx) {
+    if (step.prepareNext) {
+        return step.prepareNext(lastOutput, verdict, ctx);
+    }
+    // Requires I === O when prepareNext is omitted — the loop feeds output
+    // back as input. Callers must ensure I and O are compatible types.
+    return frameworkCast(lastOutput);
+}
+export async function executeLoop(step, input, ctx, executeStep) {
+    const baseCtx = frameworkCast(ctx);
+    let currentInput = input;
+    let lastOutput;
+    let lastText = '';
+    const history = [];
+    const startTime = Date.now();
+    let stepCount = 0;
+    const maxIterations = step.maxIterations ?? 1e3;
+    const maxHistory = step.maxHistorySize ?? 100;
+    let totalIterations = 0;
+    // Validate maxIterations
+    if (!Number.isFinite(maxIterations) || maxIterations < 1) {
+        throw new NoeticErrorImpl({
+            kind: 'step_failed',
+            stepId: step.id,
+            cause: new Error(`Invalid maxIterations: ${step.maxIterations}`),
+            retriesExhausted: false,
+        });
+    }
+    while (true) {
+        // Abort check at top of each iteration
+        if (ctx.aborted) {
+            throw new NoeticErrorImpl({
+                kind: 'cancelled',
+                reason: ctx.abortReason ?? 'context aborted',
+            });
+        }
+        // Enforce hard iteration ceiling (includes retries)
+        totalIterations++;
+        if (totalIterations > maxIterations) {
+            throw new NoeticErrorImpl({
+                kind: 'step_failed',
+                stepId: step.id,
+                cause: new Error(`Loop exceeded maximum iterations (${maxIterations})`),
+                retriesExhausted: false,
+            });
+        }
+        // Execute body steps sequentially
+        let output;
+        try {
+            let stepOutput = currentInput;
+            for (const bodyStep of step.steps) {
+                stepOutput = await executeStep(bodyStep, frameworkCast(stepOutput), ctx);
+            }
+            output = frameworkCast(stepOutput);
+            stepCount++;
+        }
+        catch (e) {
+            if (!step.onError || !isNoeticError(e)) {
+                throw e;
+            }
+            const action = step.onError(e.noeticError, ctx);
+            if (action === 'retry') {
+                continue;
+            }
+            if (action !== 'skip') {
+                throw e;
+            }
+            // Skip does not increment stepCount — it is not a successful execution.
+            if (lastOutput === undefined) {
+                continue;
+            }
+            output = lastOutput;
+        }
+        lastOutput = output;
+        history.push(output);
+        // Trim history if it exceeds maxHistorySize
+        if (history.length > maxHistory) {
+            history.splice(0, history.length - maxHistory);
+        }
+        // Extract text from output for snapshot
+        if (typeof output === 'string') {
+            lastText = output;
+        }
+        else if (hasTextField(output)) {
+            lastText = String(output.text);
+        }
+        else {
+            lastText = output === undefined ? '' : JSON.stringify(output);
+        }
+        // Build snapshot
+        const snapshot = {
+            stepCount,
+            tokens: {
+                ...ctx.tokens,
+            },
+            elapsed: Date.now() - startTime,
+            cost: ctx.cost,
+            lastOutput: output,
+            lastText,
+            history: [
+                ...history,
+            ],
+            depth: ctx.depth,
+            lastStepMeta: isMutableContext(baseCtx) ? baseCtx.lastStepMeta : null,
+        };
+        // Evaluate until predicate
+        let verdict;
+        try {
+            verdict = await step.until(snapshot);
+        }
+        catch (predicateError) {
+            // Per spec: if until predicate throws, treat as stop
+            verdict = {
+                stop: true,
+                reason: `Predicate error: ${predicateError instanceof Error ? predicateError.message : String(predicateError)}`,
+            };
+        }
+        if (verdict.stop) {
+            if (lastOutput === undefined) {
+                throw new NoeticErrorImpl({
+                    kind: 'step_failed',
+                    stepId: step.id,
+                    cause: new Error('Loop completed with no successful output'),
+                    retriesExhausted: false,
+                });
+            }
+            // Check inbox before truly stopping
+            if (step.inbox) {
+                const inboxMessage = await recvInboxWithTimeout(baseCtx, step);
+                if (inboxMessage !== null) {
+                    baseCtx.itemLog.append(createMessage(inboxMessage, 'developer'));
+                    // Continue the loop — don't stop
+                    currentInput = prepareNextInput(step, lastOutput, verdict, ctx);
+                    continue;
+                }
+            }
+            return lastOutput;
+        }
+        // Prepare input for next iteration
+        currentInput = prepareNextInput(step, output, verdict, ctx);
+    }
+}
+/** 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',
+    });
+}
+/**
+ * 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.d.ts

@@ -1,6 +1,19 @@
-import type { Context } from '../types/context';
-import type { ContextMemory } from '../types/memory';
-import type { Step } from '../types/step';
+import type { Context } from '../types/context.js';
+import type { ContextMemory } from '../types/memory.js';
+import type { Step } from '../types/step.js';
+/**
+ * @internal
+ * Dispatch a step at the per-kind handler level without adapter routing.
+ *
+ * Used as the top-level `_localExecutor` for `StepRun` / `StepSpawn`
+ * dispatches: the outer adapter call already recorded the request, so
+ * running the handler directly avoids a re-entrant adapter round-trip
+ * inside the same logical step. Nested step dispatches (e.g. `executeSpawn`
+ * descending into `step.child`) still go through `execute()` and route
+ * through the adapter as normal, so per-step overrides on descendants
+ * continue to work.
+ */
+export declare function executeNoAdapter<TMemory, I, O>(step: Step<TMemory, I, O>, input: I, ctx: Context<TMemory>): Promise<O>;
 /**
  * Executes a step within the interpreter, dispatching to the appropriate handler by step kind.
  *