@noetic-tools/core 0.0.1

package/dist/adapters/openrouter.js

@@ -0,0 +1,248 @@
+import { z } from 'zod';
+import { frameworkCast } from '../interpreter/framework-cast';
+import { isAssistantMessage } from '../interpreter/typeguards';
+import { buildToolExecutionContext } from '../runtime/tool-memory';
+import { SteeringAction } from '../types/steering';
+const EmbeddingsResponseSchema = z.object({
+    data: z.array(z.object({
+        embedding: z.array(z.number()),
+        index: z.number(),
+    })),
+});
+//#endregion
+//#region Helpers
+function isTextPart(p) {
+    return p.type === 'output_text' || p.type === 'input_text';
+}
+function contentPartsToText(parts) {
+    return parts
+        .filter(isTextPart)
+        .map((p) => p.text)
+        .join('');
+}
+//#endregion
+//#region Item → OpenRouter Input Conversion
+/** @internal Extracts system messages from items and returns them as a single instructions string. */
+export function extractSystemInstruction(items) {
+    const systemTexts = [];
+    const remaining = [];
+    for (const item of items) {
+        if (item.type === 'message' && 'role' in item && item.role === 'system') {
+            const msgItem = item;
+            systemTexts.push(contentPartsToText(msgItem.content));
+            continue;
+        }
+        remaining.push(item);
+    }
+    if (systemTexts.length === 0) {
+        return {
+            instructions: undefined,
+            remaining,
+        };
+    }
+    return {
+        instructions: systemTexts.join('\n\n'),
+        remaining,
+    };
+}
+function itemToInputItem(item) {
+    if (item.type === 'message' && 'content' in item && 'role' in item) {
+        // All message types (input and output) are converted to EasyInputMessage
+        // because the SDK's input union does not accept ResponsesOutputMessage directly.
+        return {
+            role: item.role,
+            content: contentPartsToText(item.content),
+        };
+    }
+    if (item.type === 'function_call') {
+        return {
+            type: 'function_call',
+            callId: item.callId,
+            id: item.id ?? crypto.randomUUID(),
+            name: item.name,
+            arguments: item.arguments,
+        };
+    }
+    if (item.type === 'function_call_output') {
+        return {
+            type: 'function_call_output',
+            callId: item.callId,
+            output: item.output,
+        };
+    }
+    // Reasoning, web_search_call, file_search_call, image_generation_call,
+    // server tool outputs — pass through directly for round-tripping
+    return frameworkCast(item);
+}
+/** @internal Converts Noetic Items to OpenRouter SDK input format. */
+export function itemsToInput(items) {
+    const result = [];
+    for (const item of items) {
+        const inputItem = itemToInputItem(item);
+        if (!inputItem) {
+            continue;
+        }
+        result.push(inputItem);
+    }
+    return result;
+}
+//#endregion
+//#region OpenRouter Response → Noetic Item Passthrough
+/**
+ * @internal Extracts output items from an SDK response, passing them through directly
+ * as Open Responses compliant items. Falls back to creating a message from `outputText`
+ * when the output array contains no message items.
+ */
+export function extractOutputItems(response) {
+    const items = frameworkCast(response.output);
+    const hasMessage = items.some(isAssistantMessage);
+    if (hasMessage || !response.outputText) {
+        return items;
+    }
+    // Fallback: no message items but outputText exists
+    return [
+        frameworkCast({
+            id: crypto.randomUUID(),
+            type: 'message',
+            role: 'assistant',
+            status: 'completed',
+            content: [
+                {
+                    type: 'output_text',
+                    text: response.outputText,
+                },
+            ],
+        }),
+        ...items,
+    ];
+}
+/** @internal */
+export function extractUsage(usage) {
+    if (!usage) {
+        return {
+            inputTokens: 0,
+            outputTokens: 0,
+        };
+    }
+    return {
+        inputTokens: usage.inputTokens,
+        outputTokens: usage.outputTokens,
+        cachedTokens: usage.inputTokensDetails?.cachedTokens,
+    };
+}
+//#endregion
+//#region Tool Conversion
+// We construct the SDK tool shape manually and use frameworkCast to bridge
+// the internal Zod type gap between Noetic's Tool interface and the OpenRouter SDK.
+// This is safe because callModel only uses inputSchema for JSON Schema
+// generation and validation.
+//
+// IMPORTANT: We intentionally omit `execute` from the SDK tool definitions.
+// This prevents the SDK from handling tool calls internally, which would
+// make tool interactions invisible to Noetic's itemLog, token tracking,
+// and observability. Instead, the AgentHarness manages the tool loop.
+/** @internal */
+export function convertTools({ tools }) {
+    return tools.map((t) => frameworkCast({
+        type: 'function',
+        function: {
+            name: t.name,
+            description: t.description,
+            inputSchema: t.input,
+        },
+    }));
+}
+function isAsyncGenerator(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    return Symbol.asyncIterator in value;
+}
+async function consumeGenerator(generator) {
+    let result;
+    while (true) {
+        const next = await generator.next();
+        if (next.done) {
+            result = next.value;
+            break;
+        }
+    }
+    return result;
+}
+/** @internal Execute a single tool call with steering checks. */
+export async function executeToolCall(params) {
+    const matchedTool = params.tools.find((t) => t.name === params.toolName);
+    if (!matchedTool) {
+        return {
+            output: `Error: unknown tool '${params.toolName}'`,
+            error: true,
+        };
+    }
+    if (params.layers && params.layers.length > 0) {
+        const decision = await params.harness.beforeToolCall(params.layers, params.toolName, params.args, params.context);
+        if (decision.action === SteeringAction.Deny) {
+            return {
+                output: `Tool call denied: ${decision.guidance ?? 'steering rule violation'}`,
+                error: true,
+            };
+        }
+        if (decision.action === SteeringAction.Guide) {
+            return {
+                output: `Tool call redirected: ${decision.guidance}`,
+                error: true,
+            };
+        }
+    }
+    const toolCtx = buildToolExecutionContext(params.context, params.harness);
+    try {
+        const executionResult = matchedTool.execute(params.args, toolCtx);
+        // Handle generator-based tools (like Bash) that return AsyncGenerator
+        const result = isAsyncGenerator(executionResult)
+            ? await consumeGenerator(executionResult)
+            : await executionResult;
+        return {
+            output: typeof result === 'string' ? result : JSON.stringify(result),
+            result,
+        };
+    }
+    catch (e) {
+        return {
+            output: `Error: ${e instanceof Error ? e.message : String(e)}`,
+            error: true,
+        };
+    }
+}
+//#endregion
+//#region Public API
+/**
+ * Creates an `EmbedFn` that calls the OpenRouter embeddings API.
+ *
+ * @public
+ * @param apiKey - OpenRouter API key.
+ * @param embeddingModel - Model identifier (default: `'openai/text-embedding-3-small'`).
+ * @returns An `EmbedFn` that produces embedding vectors for the given texts.
+ */
+export function createOpenRouterEmbed(apiKey, embeddingModel) {
+    const model = embeddingModel ?? 'openai/text-embedding-3-small';
+    return async (texts) => {
+        const response = await fetch('https://openrouter.ai/api/v1/embeddings', {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                model,
+                input: texts,
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`OpenRouter embeddings request failed: ${response.status} ${response.statusText}`);
+        }
+        const json = EmbeddingsResponseSchema.parse(await response.json());
+        // Sort by index to preserve input order
+        const sorted = json.data.sort((a, b) => a.index - b.index);
+        return sorted.map((d) => d.embedding);
+    };
+}
+//#endregion

package/dist/builders/channel-builder.d.ts

@@ -0,0 +1,36 @@
+import type { ZodType } from 'zod';
+import type { Channel, ExternalChannel } from '../types/channel';
+/**
+ * Creates a typed communication channel writable from outside the execution tree.
+ *
+ * @public
+ * @param name - Channel name for identification and debugging.
+ * @param opts.schema - Zod schema used to validate every message sent through the channel.
+ * @param opts.mode - Delivery semantics: `'value'` (last-write-wins), `'queue'` (FIFO), `'topic'` (pub/sub).
+ * @param opts.capacity - Buffer size for queue mode (default: 1000). Ignored for value/topic modes.
+ * @param opts.external - Must be `true` to create an externally writable channel.
+ * @returns An `ExternalChannel`.
+ */
+export declare function channel<T>(name: string, opts: {
+    schema: ZodType<T>;
+    mode: 'value' | 'queue' | 'topic';
+    capacity?: number;
+    external: true;
+}): ExternalChannel<T>;
+/**
+ * Creates a typed communication channel for inter-step messaging within an execution tree.
+ *
+ * @public
+ * @param name - Channel name for identification and debugging.
+ * @param opts.schema - Zod schema used to validate every message sent through the channel.
+ * @param opts.mode - Delivery semantics: `'value'` (last-write-wins), `'queue'` (FIFO), `'topic'` (pub/sub).
+ * @param opts.capacity - Buffer size for queue mode (default: 1000). Ignored for value/topic modes.
+ * @param opts.external - Omit or set to `false` for internal-only channels.
+ * @returns A `Channel`.
+ */
+export declare function channel<T>(name: string, opts: {
+    schema: ZodType<T>;
+    mode: 'value' | 'queue' | 'topic';
+    capacity?: number;
+    external?: false;
+}): Channel<T>;

package/dist/builders/channel-builder.js

@@ -0,0 +1,15 @@
+export function channel(name, opts) {
+    const ch = {
+        name,
+        schema: opts.schema,
+        mode: opts.mode,
+        capacity: opts.capacity,
+    };
+    if (opts.external) {
+        return {
+            ...ch,
+            external: true,
+        };
+    }
+    return ch;
+}

package/dist/builders/control-flow-builders.d.ts

@@ -0,0 +1,79 @@
+import type { Context } from '../types/context';
+import type { ContextMemory } from '../types/memory';
+import type { SettleResult, Step, StepBranch, StepForkAll, StepForkRace, StepForkSettle } from '../types/step';
+/**
+ * Creates a parallel execution step that races paths and returns the first result.
+ *
+ * @public
+ * @param opts.id - Unique step identifier used in traces and error messages.
+ * @param opts.mode - Must be `'race'`: first path to resolve wins, others are cancelled.
+ * @param opts.paths - Factory `(input, ctx) => Step[]` generating the parallel paths.
+ * @param opts.concurrency - Optional maximum number of paths to run simultaneously.
+ * @returns A `StepForkRace` step.
+ * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
+ */
+export declare function fork<TMemory = ContextMemory, I = unknown, O = unknown>(opts: {
+    id: string;
+    mode: 'race';
+    paths: (input: I, ctx: Context<TMemory>) => Step<TMemory, I, O>[];
+    concurrency?: number;
+    _optimizable?: Step<TMemory>[];
+}): StepForkRace<TMemory, I, O>;
+/**
+ * Creates a parallel execution step that waits for all paths and merges results.
+ *
+ * @public
+ * @param opts.id - Unique step identifier used in traces and error messages.
+ * @param opts.mode - Must be `'all'`: waits for every path; fails on any error.
+ * @param opts.paths - Factory `(input, ctx) => Step[]` generating the parallel paths.
+ * @param opts.merge - Combines all path results into a single output value.
+ * @param opts.concurrency - Optional maximum number of paths to run simultaneously.
+ * @returns A `StepForkAll` step.
+ * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
+ * @throws `NoeticConfigError` with code `MISSING_MERGE_FUNCTION` if `merge` is not provided.
+ */
+export declare function fork<TMemory = ContextMemory, I = unknown, O = unknown>(opts: {
+    id: string;
+    mode: 'all';
+    paths: (input: I, ctx: Context<TMemory>) => Step<TMemory, I, O>[];
+    merge: (results: O[], ctx: Context<TMemory>) => O;
+    concurrency?: number;
+    _optimizable?: Step<TMemory>[];
+}): StepForkAll<TMemory, I, O>;
+/**
+ * Creates a parallel execution step that waits for all paths, collecting errors as results.
+ *
+ * @public
+ * @param opts.id - Unique step identifier used in traces and error messages.
+ * @param opts.mode - Must be `'settle'`: waits for every path; errors are captured, not thrown.
+ * @param opts.paths - Factory `(input, ctx) => Step[]` generating the parallel paths.
+ * @param opts.merge - Combines settled results (successes and failures) into a single output.
+ * @param opts.concurrency - Optional maximum number of paths to run simultaneously.
+ * @returns A `StepForkSettle` step.
+ * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
+ * @throws `NoeticConfigError` with code `MISSING_MERGE_FUNCTION` if `merge` is not provided.
+ */
+export declare function fork<TMemory = ContextMemory, I = unknown, O = unknown>(opts: {
+    id: string;
+    mode: 'settle';
+    paths: (input: I, ctx: Context<TMemory>) => Step<TMemory, I, O>[];
+    merge: (results: SettleResult<O>[], ctx: Context<TMemory>) => O;
+    concurrency?: number;
+    _optimizable?: Step<TMemory>[];
+}): StepForkSettle<TMemory, I, O>;
+/**
+ * Creates a conditional routing step that selects the next step at runtime.
+ *
+ * @public
+ * @param opts.id - Unique step identifier used in traces and error messages.
+ * @param opts.route - Routing function `(input, ctx) => Step | null`. Returns the next step
+ *   to execute, or `null` to skip (pass input through as output). May be async.
+ * @returns A `StepBranch` step.
+ * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
+ * @throws `NoeticConfigError` with code `MISSING_ROUTE_FUNCTION` if `route` is not provided.
+ */
+export declare function branch<TMemory = ContextMemory, I = unknown, O = unknown>(opts: {
+    id: string;
+    route: (input: I, ctx: Context<TMemory>) => Step<TMemory, I, O> | null | Promise<Step<TMemory, I, O> | null>;
+    _optimizable?: Step<TMemory>[];
+}): StepBranch<TMemory, I, O>;

package/dist/builders/control-flow-builders.js

@@ -0,0 +1,53 @@
+import { NoeticConfigError } from '../errors/noetic-config-error';
+import { frameworkCast } from '../interpreter/framework-cast';
+export function fork(opts) {
+    if (!opts.id || opts.id.trim() === '') {
+        throw new NoeticConfigError({
+            code: 'EMPTY_STEP_ID',
+            message: 'fork() requires a non-empty id.',
+            hint: 'Pass a unique string as the id field, e.g. fork({ id: "my-fork", ... }).',
+        });
+    }
+    if ((opts.mode === 'all' || opts.mode === 'settle') && !opts.merge) {
+        throw new NoeticConfigError({
+            code: 'MISSING_MERGE_FUNCTION',
+            message: `fork() mode '${opts.mode}' requires a merge function.`,
+            hint: 'Provide a merge function that combines path results into a single output.',
+        });
+    }
+    return frameworkCast({
+        kind: 'fork',
+        ...opts,
+    });
+}
+/**
+ * Creates a conditional routing step that selects the next step at runtime.
+ *
+ * @public
+ * @param opts.id - Unique step identifier used in traces and error messages.
+ * @param opts.route - Routing function `(input, ctx) => Step | null`. Returns the next step
+ *   to execute, or `null` to skip (pass input through as output). May be async.
+ * @returns A `StepBranch` step.
+ * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
+ * @throws `NoeticConfigError` with code `MISSING_ROUTE_FUNCTION` if `route` is not provided.
+ */
+export function branch(opts) {
+    if (!opts.id || opts.id.trim() === '') {
+        throw new NoeticConfigError({
+            code: 'EMPTY_STEP_ID',
+            message: 'branch() requires a non-empty id.',
+            hint: 'Pass a unique string as the id field, e.g. branch({ id: "my-branch", ... }).',
+        });
+    }
+    if (!opts.route) {
+        throw new NoeticConfigError({
+            code: 'MISSING_ROUTE_FUNCTION',
+            message: 'branch() requires a route function.',
+            hint: 'Provide a route function that selects the next step at runtime.',
+        });
+    }
+    return {
+        kind: 'branch',
+        ...opts,
+    };
+}

package/dist/builders/every.d.ts

@@ -0,0 +1,45 @@
+import type { Channel } from '../types/channel';
+import type { ContextMemory } from '../types/memory';
+import type { EveryErrorPolicy, Step, StepEvery } from '../types/step';
+/**
+ * Configuration options accepted by the `every()` builder, excluding the `kind`
+ * discriminant. `every()` schedules a body step on a fixed-interval, optionally
+ * woken early by a channel, and runs until the executing context is cancelled.
+ *
+ * @public
+ */
+export interface EveryOptions<TMemory = ContextMemory, I = unknown, O = unknown> {
+    /** Unique step identifier used in traces and error messages. */
+    id: string;
+    /** Body step executed on each iteration. */
+    step: Step<TMemory, I, O>;
+    /** Park duration between iterations in milliseconds. Must be >= 0. */
+    ms: number;
+    /** Optional channel that wakes the parking interval when any value arrives. */
+    wakeOn?: Channel<unknown>;
+    /** Behavior when `step` throws. Defaults to `'continue'`. */
+    onError?: EveryErrorPolicy;
+    /** Random jitter applied to the park duration in milliseconds. Must be >= 0. Default 0. */
+    jitter?: number;
+}
+/**
+ * Creates an `every` step that runs a body step on a fixed-interval schedule.
+ *
+ * The operator runs forever until the executing context is cancelled. After each
+ * iteration it parks for `ms ± jitter` milliseconds (or until `wakeOn` receives
+ * a message, whichever comes first).
+ *
+ * @public
+ * @param opts.id - Unique step identifier used in traces and error messages.
+ * @param opts.step - Body step executed on each iteration.
+ * @param opts.ms - Park duration between iterations in milliseconds.
+ * @param opts.wakeOn - Optional channel that wakes the parking interval when any value arrives.
+ * @param opts.onError - Error policy. `'continue'` (default) records a span event and continues; `'fail'` re-throws.
+ * @param opts.jitter - Random jitter in ms applied to the park duration. Default 0.
+ * @returns A `StepEvery` step.
+ * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
+ * @throws `NoeticConfigError` with code `MISSING_BODY_STEP` if `step` is not provided.
+ * @throws `NoeticConfigError` with code `INVALID_INTERVAL_MS` if `ms` is negative or not finite.
+ * @throws `NoeticConfigError` with code `INVALID_JITTER` if `jitter` is negative or not finite.
+ */
+export declare function every<TMemory = ContextMemory, I = unknown, O = unknown>(opts: EveryOptions<TMemory, I, O>): StepEvery<TMemory, I, O>;

package/dist/builders/every.js

@@ -0,0 +1,60 @@
+import { NoeticConfigError } from '../errors/noetic-config-error';
+/**
+ * Creates an `every` step that runs a body step on a fixed-interval schedule.
+ *
+ * The operator runs forever until the executing context is cancelled. After each
+ * iteration it parks for `ms ± jitter` milliseconds (or until `wakeOn` receives
+ * a message, whichever comes first).
+ *
+ * @public
+ * @param opts.id - Unique step identifier used in traces and error messages.
+ * @param opts.step - Body step executed on each iteration.
+ * @param opts.ms - Park duration between iterations in milliseconds.
+ * @param opts.wakeOn - Optional channel that wakes the parking interval when any value arrives.
+ * @param opts.onError - Error policy. `'continue'` (default) records a span event and continues; `'fail'` re-throws.
+ * @param opts.jitter - Random jitter in ms applied to the park duration. Default 0.
+ * @returns A `StepEvery` step.
+ * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
+ * @throws `NoeticConfigError` with code `MISSING_BODY_STEP` if `step` is not provided.
+ * @throws `NoeticConfigError` with code `INVALID_INTERVAL_MS` if `ms` is negative or not finite.
+ * @throws `NoeticConfigError` with code `INVALID_JITTER` if `jitter` is negative or not finite.
+ */
+export function every(opts) {
+    if (!opts.id || opts.id.trim() === '') {
+        throw new NoeticConfigError({
+            code: 'EMPTY_STEP_ID',
+            message: 'every() requires a non-empty id.',
+            hint: 'Pass a unique string as the id field, e.g. every({ id: "my-every", ... }).',
+        });
+    }
+    if (!opts.step) {
+        throw new NoeticConfigError({
+            code: 'MISSING_BODY_STEP',
+            message: 'every() requires a body step.',
+            hint: 'Provide the step to execute on each scheduled iteration.',
+        });
+    }
+    if (!Number.isFinite(opts.ms) || opts.ms < 0) {
+        throw new NoeticConfigError({
+            code: 'INVALID_INTERVAL_MS',
+            message: `every() requires a non-negative finite ms, got ${opts.ms}.`,
+            hint: 'Pass a non-negative number of milliseconds for the park interval.',
+        });
+    }
+    if (opts.jitter !== undefined && (!Number.isFinite(opts.jitter) || opts.jitter < 0)) {
+        throw new NoeticConfigError({
+            code: 'INVALID_JITTER',
+            message: `every() requires a non-negative finite jitter, got ${opts.jitter}.`,
+            hint: 'Pass a non-negative number of milliseconds for jitter, or omit it.',
+        });
+    }
+    return {
+        kind: 'every',
+        id: opts.id,
+        step: opts.step,
+        ms: opts.ms,
+        wakeOn: opts.wakeOn,
+        onError: opts.onError ?? 'continue',
+        jitter: opts.jitter ?? 0,
+    };
+}

package/dist/builders/layer-provides-builders.d.ts

@@ -0,0 +1,32 @@
+import type { ZodType } from 'zod';
+import type { ExecutionContext, LayerDataDecl, LayerFunctionDecl } from '../types/memory';
+/**
+ * Creates a read-only data declaration for a memory layer's `provides` map.
+ *
+ * @public
+ * @param opts.read - Function that projects a value from the layer's current state.
+ * @returns A `LayerDataDecl` to include in a layer's `provides`.
+ */
+export declare function layerData<T, TState>(opts: {
+    read: (state: TState) => T;
+}): LayerDataDecl<T, TState>;
+/**
+ * Creates a callable function declaration for a memory layer's `provides` map.
+ * Functions are accessible via `ctx.memory['layerId'].fn()` and automatically exposed as LLM tools.
+ *
+ * @public
+ * @param opts.description - Human-readable description (used as tool description for LLM).
+ * @param opts.input - Zod schema validating input arguments.
+ * @param opts.output - Zod schema validating the return value.
+ * @param opts.execute - Async function receiving args, current state, and execution context.
+ * @returns A `LayerFunctionDecl` to include in a layer's `provides`.
+ */
+export declare function layerFn<TInput, TOutput, TState>(opts: {
+    description: string;
+    input: ZodType<TInput>;
+    output: ZodType<TOutput>;
+    execute: (args: TInput, state: TState, ctx: ExecutionContext) => Promise<{
+        result: TOutput;
+        state?: TState;
+    }>;
+}): LayerFunctionDecl<TInput, TOutput, TState>;

package/dist/builders/layer-provides-builders.js

@@ -0,0 +1,33 @@
+/**
+ * Creates a read-only data declaration for a memory layer's `provides` map.
+ *
+ * @public
+ * @param opts.read - Function that projects a value from the layer's current state.
+ * @returns A `LayerDataDecl` to include in a layer's `provides`.
+ */
+export function layerData(opts) {
+    return {
+        kind: 'data',
+        read: opts.read,
+    };
+}
+/**
+ * Creates a callable function declaration for a memory layer's `provides` map.
+ * Functions are accessible via `ctx.memory['layerId'].fn()` and automatically exposed as LLM tools.
+ *
+ * @public
+ * @param opts.description - Human-readable description (used as tool description for LLM).
+ * @param opts.input - Zod schema validating input arguments.
+ * @param opts.output - Zod schema validating the return value.
+ * @param opts.execute - Async function receiving args, current state, and execution context.
+ * @returns A `LayerFunctionDecl` to include in a layer's `provides`.
+ */
+export function layerFn(opts) {
+    return {
+        kind: 'function',
+        description: opts.description,
+        input: opts.input,
+        output: opts.output,
+        execute: opts.execute,
+    };
+}

package/dist/builders/loop-builder.d.ts

@@ -0,0 +1,23 @@
+import type { ContextMemory } from '../types/memory';
+import type { StepLoop } from '../types/step';
+/** @public Configuration options accepted by the `loop()` builder, excluding the `kind` discriminant. */
+export type LoopConfig<TMemory = ContextMemory, I = unknown, O = unknown> = Omit<StepLoop<TMemory, I, O>, 'kind'>;
+/**
+ * Creates a loop step that iterates a body step until a termination predicate is satisfied.
+ *
+ * @public
+ * @param opts.id - Unique step identifier used in traces and error messages.
+ * @param opts.steps - Array of steps to execute sequentially on each iteration.
+ * @param opts.until - Termination predicate `(snapshot) => Verdict | Promise<Verdict>` evaluated after each iteration.
+ * @param opts.maxIterations - Hard safety cap on iterations (default: 1000).
+ * @param opts.maxHistorySize - Maximum entries kept in the snapshot history array.
+ * @param opts.inbox - Optional channel for injecting messages into the loop mid-execution.
+ * @param opts.parkTimeout - Ms to wait on inbox before the loop parks itself (default: 0).
+ * @param opts.prepareNext - Transforms `(output, verdict, ctx)` into the next iteration's input.
+ * @param opts.onError - Per-iteration error handler returning `'retry'`, `'skip'`, or `'abort'`.
+ * @returns A `StepLoop` step.
+ * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
+ * @throws `NoeticConfigError` with code `MISSING_LOOP_BODY` if `steps` is empty.
+ * @throws `NoeticConfigError` with code `MISSING_UNTIL_PREDICATE` if `until` is not provided.
+ */
+export declare function loop<TMemory = ContextMemory, I = unknown, O = unknown>(opts: LoopConfig<TMemory, I, O>): StepLoop<TMemory, I, O>;

package/dist/builders/loop-builder.js

@@ -0,0 +1,46 @@
+import { NoeticConfigError } from '../errors/noetic-config-error';
+/**
+ * Creates a loop step that iterates a body step until a termination predicate is satisfied.
+ *
+ * @public
+ * @param opts.id - Unique step identifier used in traces and error messages.
+ * @param opts.steps - Array of steps to execute sequentially on each iteration.
+ * @param opts.until - Termination predicate `(snapshot) => Verdict | Promise<Verdict>` evaluated after each iteration.
+ * @param opts.maxIterations - Hard safety cap on iterations (default: 1000).
+ * @param opts.maxHistorySize - Maximum entries kept in the snapshot history array.
+ * @param opts.inbox - Optional channel for injecting messages into the loop mid-execution.
+ * @param opts.parkTimeout - Ms to wait on inbox before the loop parks itself (default: 0).
+ * @param opts.prepareNext - Transforms `(output, verdict, ctx)` into the next iteration's input.
+ * @param opts.onError - Per-iteration error handler returning `'retry'`, `'skip'`, or `'abort'`.
+ * @returns A `StepLoop` step.
+ * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
+ * @throws `NoeticConfigError` with code `MISSING_LOOP_BODY` if `steps` is empty.
+ * @throws `NoeticConfigError` with code `MISSING_UNTIL_PREDICATE` if `until` is not provided.
+ */
+export function loop(opts) {
+    if (!opts.id || opts.id.trim() === '') {
+        throw new NoeticConfigError({
+            code: 'EMPTY_STEP_ID',
+            message: 'loop() requires a non-empty id.',
+            hint: 'Pass a unique string as the id field, e.g. loop({ id: "my-loop", ... }).',
+        });
+    }
+    if (!Array.isArray(opts.steps) || opts.steps.length === 0) {
+        throw new NoeticConfigError({
+            code: 'MISSING_LOOP_BODY',
+            message: 'loop() requires at least one body step.',
+            hint: 'Add at least one step to the steps array.',
+        });
+    }
+    if (!opts.until) {
+        throw new NoeticConfigError({
+            code: 'MISSING_UNTIL_PREDICATE',
+            message: 'loop() requires an until predicate.',
+            hint: 'Provide an until predicate, e.g. until.maxSteps(10).',
+        });
+    }
+    return {
+        kind: 'loop',
+        ...opts,
+    };
+}