@noetic-tools/core 0.0.1

package/dist/interpreter/execute-llm.js

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

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

package/dist/interpreter/execute-loop.js

@@ -0,0 +1,171 @@
+import { isNoeticError, NoeticErrorImpl } from '../errors/noetic-error';
+import { frameworkCast } from './framework-cast';
+import { createMessage } from './message-helpers';
+import { isMutableContext } from './typeguards';
+//#endregion
+//#region Helper Functions
+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);
+}
+//#endregion
+//#region Public API
+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);
+    }
+}
+//#endregion

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

@@ -0,0 +1,10 @@
+import type { Context } from '../types/context';
+import type { ExecuteStepFn, StepProvide } from '../types/step';
+/**
+ * Executes a provide step by attaching memory layers to the current context
+ * without creating an isolated child context.
+ *
+ * Unlike spawn, provide does not create a new itemLog or clone state.
+ * Events flow through to the parent in real-time.
+ */
+export declare function executeProvide<TMemory, I, O>(step: StepProvide<TMemory, I, O>, input: I, ctx: Context<TMemory>, executeStep: ExecuteStepFn): Promise<O>;

package/dist/interpreter/execute-provide.js

@@ -0,0 +1,64 @@
+import { resolveLayerTools } from '../memory/layer-api';
+import { deduplicateTools } from './collect-tools';
+import { frameworkCast } from './framework-cast';
+//#region Helper Functions
+function isMemoryConfig(value) {
+    return typeof value === 'object' && value !== null && 'layers' in value;
+}
+function resolveLayers(step) {
+    if (isMemoryConfig(step.memory)) {
+        return [
+            ...step.memory.layers,
+        ];
+    }
+    return step.memory;
+}
+function mergeLayers(existing, provided) {
+    if (!existing || existing.length === 0) {
+        return provided;
+    }
+    // Provided layers override existing layers with the same id (like nested React context)
+    const providedIds = new Set(provided.map((l) => l.id));
+    const kept = existing.filter((l) => !providedIds.has(l.id));
+    return [
+        ...kept,
+        ...provided,
+    ];
+}
+//#endregion
+//#region Public API
+/**
+ * Executes a provide step by attaching memory layers to the current context
+ * without creating an isolated child context.
+ *
+ * Unlike spawn, provide does not create a new itemLog or clone state.
+ * Events flow through to the parent in real-time.
+ */
+export async function executeProvide(step, input, ctx, executeStep) {
+    const baseCtx = frameworkCast(ctx);
+    const previousLayers = baseCtx.layers;
+    const previousUnifiedTools = baseCtx.unifiedTools;
+    const newLayers = resolveLayers(step);
+    const mergedLayers = mergeLayers(previousLayers, newLayers);
+    // Attach layers to the current context (no isolation)
+    baseCtx.layers = mergedLayers;
+    // Merge new layer-provided tools into the unified tool set
+    if (baseCtx.unifiedTools && newLayers.length > 0) {
+        const layerTools = resolveLayerTools(newLayers, baseCtx.harness, baseCtx);
+        if (layerTools.length > 0) {
+            baseCtx.unifiedTools = deduplicateTools([
+                ...baseCtx.unifiedTools,
+                ...layerTools,
+            ]);
+        }
+    }
+    try {
+        return await executeStep(step.child, input, ctx);
+    }
+    finally {
+        // Restore previous layers and unified tools so siblings are not affected
+        baseCtx.layers = previousLayers;
+        baseCtx.unifiedTools = previousUnifiedTools;
+    }
+}
+//#endregion

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

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

package/dist/interpreter/execute-run.js

@@ -0,0 +1,39 @@
+import { NoeticErrorImpl } from '../errors/noetic-error';
+export async function executeRun(step, input, ctx) {
+    const retry = step.retry;
+    const maxAttempts = retry?.maxAttempts ?? 1;
+    let lastError = new Error('No attempts executed');
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+            return await step.execute(input, ctx);
+        }
+        catch (e) {
+            lastError = e instanceof Error ? e : new Error(String(e));
+            if (attempt < maxAttempts - 1 && retry) {
+                const delay = computeDelay(retry, attempt);
+                await new Promise((r) => setTimeout(r, delay));
+            }
+        }
+    }
+    throw new NoeticErrorImpl({
+        kind: 'step_failed',
+        stepId: step.id,
+        cause: lastError,
+        retriesExhausted: maxAttempts > 1,
+    });
+}
+function computeDelay(retry, attempt) {
+    let delay;
+    switch (retry.backoff) {
+        case 'fixed':
+            delay = retry.initialDelay;
+            break;
+        case 'linear':
+            delay = retry.initialDelay * (attempt + 1);
+            break;
+        case 'exponential':
+            delay = retry.initialDelay * 2 ** attempt;
+            break;
+    }
+    return Math.min(delay, retry.maxDelay ?? 30_000);
+}

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

@@ -0,0 +1,11 @@
+import type { LayerStateStore } from '../memory/layer-lifecycle';
+import type { ItemSchemaRegistry } from '../schemas/item';
+import type { Context } from '../types/context';
+import type { MemoryLayer } from '../types/memory';
+import type { ExecuteStepFn, StepSpawn } from '../types/step';
+export interface ExecuteSpawnOpts {
+    layerStore?: LayerStateStore;
+    parentLayers?: MemoryLayer[];
+    itemSchemas?: ItemSchemaRegistry;
+}
+export declare function executeSpawn<TMemory, I, O>(step: StepSpawn<TMemory, I, O>, input: I, ctx: Context<TMemory>, executeStep: ExecuteStepFn, opts?: ExecuteSpawnOpts): Promise<O>;

package/dist/interpreter/execute-spawn.js

@@ -0,0 +1,113 @@
+import { resolveLayerTools } from '../memory/layer-api';
+import { returnLayers, spawnLayers } from '../memory/layer-lifecycle';
+import { ContextImpl } from '../runtime/context-impl';
+import { snapshotCwdState } from '../runtime/cwd-helpers';
+import { contextToExecCtx } from '../runtime/exec-context-factory';
+import { defaultItemSchemaRegistry } from '../schemas/item';
+import { cloneWithGuard } from './clone-guard';
+import { collectAllTools, deduplicateTools } from './collect-tools';
+import { frameworkCast } from './framework-cast';
+import { getContextChannelStore } from './typeguards';
+//#endregion
+//#region Helper Functions
+function isMemoryConfig(value) {
+    return typeof value === 'object' && value !== null && 'layers' in value;
+}
+function resolveLayersForSpawn(step, parentLayers) {
+    if (!step.memory) {
+        return parentLayers ?? [];
+    }
+    if (isMemoryConfig(step.memory)) {
+        return [
+            ...step.memory.layers,
+        ];
+    }
+    return step.memory;
+}
+async function collectSpawnItems({ layers, parentExecutionCtx, childExecutionCtx, layerStore, itemSchemas = defaultItemSchemaRegistry, }) {
+    const spawnResults = await spawnLayers({
+        layers,
+        parentCtx: parentExecutionCtx,
+        childCtx: childExecutionCtx,
+        store: layerStore,
+        itemSchemas,
+    });
+    return spawnResults.flatMap((r) => r.items);
+}
+//#endregion
+//#region Public API
+export async function executeSpawn(step, input, ctx, executeStep, opts) {
+    const baseCtx = frameworkCast(ctx);
+    const layers = resolveLayersForSpawn(step, opts?.parentLayers);
+    const childId = crypto.randomUUID();
+    const childExecutionCtx = contextToExecCtx(baseCtx, {
+        executionId: childId,
+        depth: baseCtx.depth + 1,
+        stepNumber: 0,
+        tokenUsage: {
+            input: 0,
+            output: 0,
+        },
+        cost: 0,
+        readLayerStateId: childId,
+    });
+    const layerStore = opts?.layerStore;
+    const hasLayers = layers.length > 0 && layerStore !== undefined;
+    // Collect items from memory layers via onSpawn hooks
+    let childItems = [];
+    let parentExecutionCtx;
+    if (hasLayers) {
+        parentExecutionCtx = contextToExecCtx(baseCtx);
+        childItems = await collectSpawnItems({
+            layers,
+            parentExecutionCtx,
+            childExecutionCtx,
+            layerStore,
+            itemSchemas: opts?.itemSchemas,
+        });
+    }
+    // Build unified tool set for child from its step tree + layers
+    const childStepTools = collectAllTools(step.child);
+    const childLayerTools = layers.length > 0 ? resolveLayerTools(layers, baseCtx.harness, baseCtx) : [];
+    const childUnifiedTools = deduplicateTools([
+        ...childStepTools,
+        ...childLayerTools,
+    ]);
+    // Create child context — empty by default, layers provide items via onSpawn.
+    const childCtx = new ContextImpl({
+        harness: baseCtx.harness,
+        parent: baseCtx,
+        items: childItems,
+        state: cloneWithGuard(baseCtx.state, `Spawn '${step.id}'`),
+        threadId: baseCtx.threadId,
+        resourceId: baseCtx.resourceId,
+        channelStore: getContextChannelStore(baseCtx),
+        layers: layers.length > 0 ? layers : undefined,
+        unifiedTools: childUnifiedTools.length > 0 ? childUnifiedTools : undefined,
+        cwdState: snapshotCwdState(baseCtx),
+    });
+    try {
+        // Execute the child step
+        const childOutput = await executeStep(step.child, input, frameworkCast(childCtx));
+        // Pipeline result through layer onReturn hooks
+        if (!hasLayers || !parentExecutionCtx) {
+            return childOutput;
+        }
+        const pipelinedResult = await returnLayers({
+            layers,
+            parentCtx: parentExecutionCtx,
+            childCtx: childExecutionCtx,
+            childLog: childCtx.itemLog,
+            result: childOutput,
+            store: layerStore,
+        });
+        return pipelinedResult;
+    }
+    finally {
+        // Clean up child execution state to prevent memory leaks — runs on success and error
+        if (hasLayers) {
+            layerStore.cleanup(childExecutionCtx.executionId);
+        }
+    }
+}
+//#endregion

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

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