@noetic-tools/core 0.0.1 → 0.1.1

package/dist/interpreter/execute-loop.js

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

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

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

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

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

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

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

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

package/dist/interpreter/execute-tool.js

@@ -1,81 +0,0 @@
-import { NoeticErrorImpl } from '../errors/noetic-error';
-import { emitFrameworkEvent, getBroadcaster } from '../runtime/broadcaster-utils';
-import { buildToolExecutionContext } from '../runtime/tool-memory';
-import { SteeringAction } from '../types/steering';
-import { frameworkCast } from './framework-cast';
-//#region Helpers
-function isAsyncGenerator(value) {
-    if (typeof value !== 'object' || value === null) {
-        return false;
-    }
-    return Symbol.asyncIterator in value;
-}
-async function consumeToolGenerator(params) {
-    const broadcaster = getBroadcaster(params.ctx);
-    const agentName = params.ctx.harness.config.name;
-    while (true) {
-        const next = await params.generator.next();
-        if (next.done) {
-            return next.value;
-        }
-        emitFrameworkEvent({
-            broadcaster,
-            agentName,
-            eventType: 'tool_progress',
-            data: {
-                stepId: params.stepId,
-                toolName: params.toolName,
-                event: next.value,
-            },
-        });
-    }
-}
-//#endregion
-//#region Public API
-export async function executeTool(step, input, ctx, harness, layers) {
-    const baseCtx = frameworkCast(ctx);
-    const args = step.args ? Object.assign({}, input, step.args) : input;
-    const parseResult = step.tool.input.safeParse(args);
-    if (!parseResult.success) {
-        throw new NoeticErrorImpl({
-            kind: 'step_failed',
-            stepId: step.id,
-            cause: new Error(`Tool input validation failed: ${parseResult.error.message}`),
-            retriesExhausted: false,
-        });
-    }
-    if (layers && layers.length > 0) {
-        const decision = await harness.beforeToolCall(layers, step.tool.name, parseResult.data, baseCtx);
-        if (decision.action !== SteeringAction.Allow) {
-            throw new NoeticErrorImpl({
-                kind: 'steering_denied',
-                guidance: decision.guidance,
-            });
-        }
-    }
-    try {
-        const toolCtx = buildToolExecutionContext(baseCtx, harness);
-        const result = step.tool.execute(parseResult.data, toolCtx);
-        if (isAsyncGenerator(result)) {
-            return frameworkCast(await consumeToolGenerator({
-                generator: result,
-                stepId: step.id,
-                toolName: step.tool.name,
-                ctx: baseCtx,
-            }));
-        }
-        return frameworkCast(await result);
-    }
-    catch (e) {
-        if (e instanceof NoeticErrorImpl) {
-            throw e;
-        }
-        throw new NoeticErrorImpl({
-            kind: 'step_failed',
-            stepId: step.id,
-            cause: e instanceof Error ? e : new Error(String(e)),
-            retriesExhausted: false,
-        });
-    }
-}
-//#endregion