@noetic-tools/core 0.0.1 → 0.1.1

package/dist/interpreter/execute-action.js

@@ -0,0 +1,527 @@
+/**
+ * Action step handlers: run, llm, spawn, provide, tool.
+ */
+import { ZodError } from 'zod';
+import { NoeticConfigError } from '../errors/noetic-config-error.js';
+import { NoeticErrorImpl } from '../errors/noetic-error.js';
+import { frameworkCast } from '../util/framework-cast.js';
+import { createMessage, extractAssistantText } from '../util/message-helpers.js';
+import { assembleView, buildToolExecutionContext, ContextImpl, commitLayerUsage, computeLayerUsage, contextToExecCtx, defaultItemSchemaRegistry, emitFrameworkEvent, getBroadcaster, resolveLayerTools, returnLayers, snapshotCwdState, spawnLayers, } from './action-deps.js';
+import { SteeringAction } from './action-types.js';
+import { cloneWithGuard } from './clone-guard.js';
+import { collectAllTools, deduplicateTools } from './collect-tools.js';
+import { trackUsage } from './message-helpers.js';
+import { getContextChannelStore, isFunctionCall, isMutableContext } from './typeguards.js';
+//#region run
+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);
+}
+//#endregion
+//#region llm
+const MAX_STEERING_RETRIES = 3;
+const emptyRecall = [];
+/**
+ * Resolves a `Lazy<T>` step field. If the value is a function, it is invoked
+ * with the current context; otherwise the value is returned as-is. Supports
+ * both sync and async getters.
+ *
+ * Lazy fields let a step inspect `ctx.harness.config.params`, `ctx.unifiedTools`,
+ * or memory layer state to produce per-execution values (model, instructions,
+ * tools) without baking them in at build time.
+ */
+async function resolveLazy(value, ctx) {
+    if (typeof value !== 'function') {
+        return value;
+    }
+    // The `function` narrowing collapses to `T & Function` when `T` itself can
+    // be a function, so we defer to `frameworkCast` — the single sanctioned
+    // unsafe coercion helper. Runtime check above guarantees safety.
+    const getter = frameworkCast(value);
+    return await getter(ctx);
+}
+/**
+ * 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(stepTools, layers, ctx) {
+    // stepTools = [] → explicit opt-out
+    if (stepTools && stepTools.length === 0) {
+        return {
+            tools: undefined,
+            allowedToolNames: undefined,
+        };
+    }
+    const unified = ctx.unifiedTools;
+    if (unified && unified.length > 0) {
+        const allowedToolNames = stepTools ? stepTools.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 && !stepTools) {
+        return {
+            tools: undefined,
+            allowedToolNames: undefined,
+        };
+    }
+    const merged = [
+        ...(stepTools ?? []),
+        ...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);
+    }
+}
+export async function executeLLM(step, input, ctx, layers) {
+    const baseCtx = frameworkCast(ctx);
+    const hasLayers = layers !== undefined && layers.length > 0;
+    // Resolve lazy step fields up-front. Function-form getters run once per
+    // step execution with the live context, so `ctx.harness.config.params`,
+    // `ctx.unifiedTools`, and memory layer state are all visible at resolution.
+    const resolvedModel = await resolveLazy(step.model, ctx);
+    if (!resolvedModel || resolvedModel.trim() === '') {
+        throw new NoeticConfigError({
+            code: 'MISSING_MODEL',
+            message: `step.llm(${JSON.stringify(step.id)}) resolved model to an empty string.`,
+            hint: "Ensure `model` (or your `(ctx) => string` getter) returns a non-empty identifier, e.g. 'anthropic/claude-sonnet-4-20250514'.",
+        });
+    }
+    const resolvedInstructions = await resolveLazy(step.instructions, ctx);
+    const resolvedStepTools = await resolveLazy(step.tools, ctx);
+    // 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(resolvedStepTools, 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: resolvedModel,
+                items: assembledItems,
+                instructions: resolvedInstructions,
+                tools: resolvedTools,
+                params: step.params,
+                outputSchema: step.output,
+                emit: step.emit,
+                ctx: baseCtx,
+                layers,
+                allowedToolNames,
+            }
+            : {
+                model: resolvedModel,
+                items: assembledItems,
+                instructions: resolvedInstructions,
+                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: resolvedModel,
+            instructions: resolvedInstructions,
+            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,
+    });
+}
+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);
+}
+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.
+    // `id: childId` keeps the ContextImpl's id in sync with the executionId
+    // used by spawnLayers/returnLayers in the layer-state store, so writes via
+    // `ctx.memory[layerId]` and spawn-boundary hooks read from the same key.
+    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),
+        id: childId,
+    });
+    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
+//#region provide
+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,
+    ];
+}
+/**
+ * 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
+//#region tool
+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,
+            },
+        });
+    }
+}
+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

package/dist/interpreter/{execute-every.d.ts → execute-control.d.ts}

@@ -1,5 +1,11 @@
-import type { Context } from '../types/context';
-import type { ExecuteStepFn, StepEvery } from '../types/step';
+/**
+ * Control-flow step handlers: branch, fork, loop, every.
+ */
+import type { Context } from '../types/context.js';
+import type { ExecuteStepFn, StepBranch, StepEvery, StepFork, StepLoop } from '../types/step.js';
+export declare function executeBranch<TMemory, I, O>(step: StepBranch<TMemory, I, O>, input: I, ctx: Context<TMemory>, executeStep: ExecuteStepFn): Promise<O>;
+export declare function executeFork<TMemory, I, O>(step: StepFork<TMemory, I, O>, input: I, ctx: Context<TMemory>, executeStep: ExecuteStepFn): Promise<O>;
+export declare function executeLoop<TMemory, I, O>(step: StepLoop<TMemory, I, O>, input: I, ctx: Context<TMemory>, executeStep: ExecuteStepFn): Promise<O>;
 /**
  * Executes an `every` step: runs the body step forever, paced by `ms ± jitter`,
  * woken early by `wakeOn`. Throws `cancelled` when the context is aborted.