@noetic-tools/core 0.0.1 → 0.1.1

package/dist/builders/step-builders.js

@@ -1,4 +1,7 @@
-import { NoeticConfigError } from '../errors/noetic-config-error';
+import { NoeticConfigError } from '../errors/noetic-config-error.js';
+import { getDefaultRegistrar } from '../types/step-registrar.js';
+//#endregion
+//#region Builders
 export const step = {
     /**
      * Creates a pure async computation step.
@@ -7,9 +10,13 @@ export const step = {
      * @param opts.id - Unique step identifier used in traces and error messages.
      * @param opts.execute - Async function `(input, ctx) => output` that performs the work.
      * @param opts.retry - Optional retry policy controlling attempts, backoff, and delay.
-     * @returns A `StepRun` that can be composed into larger pipelines.
+     * @param opts.subprocess - Optional per-step subprocess adapter override.
+     * @returns A `StepRun` that can be composed into larger pipelines. The step
+     *   is auto-registered in the shared step registry so the subprocess
+     *   adapter can dispatch it by id.
      * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
      * @throws `NoeticConfigError` with code `MISSING_EXECUTE_FUNCTION` if `execute` is not provided.
+     * @throws `NoeticConfigError` with code `DUPLICATE_STEP_ID` if another step with the same id is already registered with a different body.
      */
     run(opts) {
         if (!opts.id || opts.id.trim() === '') {
@@ -26,24 +33,27 @@ export const step = {
                 hint: 'Provide an async execute function, e.g. execute: async (input, ctx) => result.',
             });
         }
-        return {
+        const built = {
             kind: 'run',
             ...opts,
         };
+        getDefaultRegistrar().register(built);
+        return built;
     },
     /**
      * Creates an LLM model call step with optional tools and structured output.
      *
      * @public
      * @param opts.id - Unique step identifier used in traces and error messages.
-     * @param opts.model - Model identifier string (e.g. `'anthropic/claude-sonnet-4-20250514'`).
-     * @param opts.instructions - Optional system prompt / instructions for the model.
-     * @param opts.tools - Optional tools available to the model during this call.
+     * @param opts.model - Model identifier, eager string or `(ctx) => string` getter (resolved at step execution time).
+     * @param opts.instructions - Optional system prompt; eager string or `(ctx) => string | undefined` getter.
+     * @param opts.tools - Optional tools; eager array or `(ctx) => Tool[] | undefined` getter.
      * @param opts.output - Optional Zod schema enabling structured output parsing.
      * @param opts.params - Optional model parameters (temperature, topP, maxTokens, stopSequences).
-     * @returns A `StepLLM` that can be composed into larger pipelines.
+     * @returns A `StepLLM` that can be composed into larger pipelines. The step
+     *   is auto-registered in the shared step registry.
      * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
-     * @throws `NoeticConfigError` with code `MISSING_MODEL` if `model` is empty.
+     * @throws `NoeticConfigError` with code `MISSING_MODEL` if an eager `model` string is empty. Function-form models are validated at step execution.
      */
     llm(opts) {
         if (!opts.id || opts.id.trim() === '') {
@@ -53,17 +63,22 @@ export const step = {
                 hint: 'Pass a unique string as the id field, e.g. step.llm({ id: "my-llm", ... }).',
             });
         }
-        if (!opts.model || opts.model.trim() === '') {
+        // Only validate eager models here. Function-form models are validated
+        // post-resolution in executeLLM so the same MISSING_MODEL error surfaces
+        // whether the caller passes a string or a getter.
+        if (typeof opts.model === 'string' && opts.model.trim() === '') {
             throw new NoeticConfigError({
                 code: 'MISSING_MODEL',
                 message: 'step.llm() requires a non-empty model.',
                 hint: "Pass a model identifier, e.g. model: 'anthropic/claude-sonnet-4-20250514'.",
             });
         }
-        return {
+        const built = {
             kind: 'llm',
             ...opts,
         };
+        getDefaultRegistrar().register(built);
+        return built;
     },
     /**
      * Creates a tool execution step that invokes a typed tool definition.
@@ -72,7 +87,8 @@ export const step = {
      * @param opts.id - Unique step identifier used in traces and error messages.
      * @param opts.tool - The tool definition with typed input/output schemas.
      * @param opts.args - Optional partial args that override or supplement LLM-provided arguments.
-     * @returns A `StepTool` that can be composed into larger pipelines.
+     * @returns A `StepTool` that can be composed into larger pipelines. The step
+     *   is auto-registered in the shared step registry.
      * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
      * @throws `NoeticConfigError` with code `MISSING_TOOL` if `tool` is not provided.
      */
@@ -91,9 +107,12 @@ export const step = {
                 hint: 'Provide a tool definition created with the tool() builder.',
             });
         }
-        return {
+        const built = {
             kind: 'tool',
             ...opts,
         };
+        getDefaultRegistrar().register(built);
+        return built;
     },
 };
+//#endregion

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

@@ -1,7 +1,7 @@
 import type { ZodTypeAny, z } from 'zod';
-import type { Tool } from '../types/common';
-import type { FunctionCallItem, FunctionCallOutputItem, Item, ItemSchemaExtensions, ToolResultExtensionItem } from '../types/items';
-import type { ToolExecutionContext } from '../types/tool-context';
+import type { FunctionCallItem, FunctionCallOutputItem, Item, ItemSchemaExtensions, ToolResultExtensionItem } from '../types/items.js';
+import type { Tool, ToolMemoryDeclaration } from '../types/tool.js';
+import type { ToolExecutionContext } from '../types/tool-context.js';
 interface ToolConfig<I extends ZodTypeAny, O extends ZodTypeAny> {
     name: string;
     description: string;
@@ -18,6 +18,8 @@ interface ToolConfig<I extends ZodTypeAny, O extends ZodTypeAny> {
     }) => Item | ToolResultExtensionItem;
     execute: (args: z.infer<I>, toolCtx: ToolExecutionContext) => Promise<z.infer<O>>;
     needsApproval?: boolean;
+    /** Optional memory declaration — the runtime generates a MemoryLayer from this via toolMemoryLayer(). */
+    memory?: ToolMemoryDeclaration;
 }
 interface GeneratorToolConfig<I extends ZodTypeAny, E extends ZodTypeAny, O extends ZodTypeAny> {
     name: string;
@@ -36,6 +38,8 @@ interface GeneratorToolConfig<I extends ZodTypeAny, E extends ZodTypeAny, O exte
     }) => Item | ToolResultExtensionItem;
     execute: (args: z.infer<I>, toolCtx: ToolExecutionContext) => AsyncGenerator<z.infer<E>, z.infer<O>>;
     needsApproval?: boolean;
+    /** Optional memory declaration — the runtime generates a MemoryLayer from this via toolMemoryLayer(). */
+    memory?: ToolMemoryDeclaration;
 }
 /**
  * Creates a typed Tool with Zod schema inference for input and output.

package/dist/builders/tool-builder.js

@@ -1,4 +1,4 @@
-import { NoeticConfigError } from '../errors/noetic-config-error';
+import { NoeticConfigError } from '../errors/noetic-config-error.js';
 //#endregion
 //#region Helpers
 function validateToolConfig(name, execute) {
@@ -35,6 +35,7 @@ export function tool(config) {
         decorateResultItem: config.decorateResultItem,
         execute: config.execute,
         needsApproval: config.needsApproval,
+        memory: config.memory,
     };
 }
 /**
@@ -54,6 +55,7 @@ export function toolWithGenerator(config) {
         decorateResultItem: config.decorateResultItem,
         execute: config.execute,
         needsApproval: config.needsApproval,
+        memory: config.memory,
     };
 }
 //#endregion

package/dist/builders/workflow-hydrator.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Converts a validated `WorkflowDocument` into a live `Step` tree.
+ *
+ * Each node kind maps to the corresponding builder (`step.llm`, `fork`,
+ * `loop`, etc.) so hydrated steps are indistinguishable from programmatic
+ * ones — they register in the step registry, carry retry policies, etc.
+ */
+import type { WorkflowDocument, WorkflowNode } from '../schemas/workflow.js';
+import type { ContextMemory, MemoryLayer } from '../types/memory.js';
+import type { ExecuteStepFn, Step } from '../types/step.js';
+import type { Tool } from '../types/tool.js';
+/** @public Context required to hydrate a JSON workflow into live steps. */
+export interface HydrationContext {
+    tools: ReadonlyMap<string, Tool>;
+    executeStep: ExecuteStepFn;
+    layers?: ReadonlyMap<string, MemoryLayer>;
+}
+/**
+ * Hydrates a single `WorkflowNode` into a live `Step`.
+ *
+ * @public
+ * @param node - Validated workflow node.
+ * @param ctx - Hydration context with tool registry and step executor.
+ * @returns A live `Step` ready for execution.
+ * @throws `NoeticConfigError` with code `UNKNOWN_NODE_KIND` if the node kind is unrecognised.
+ * @throws `NoeticConfigError` with code `UNKNOWN_TOOL_REFERENCE` if a tool name cannot be resolved.
+ * @throws `NoeticConfigError` with code `UNKNOWN_UNTIL_PREDICATE` if an until predicate kind is unrecognised.
+ */
+export declare function hydrateNode(node: WorkflowNode, ctx: HydrationContext): Step<ContextMemory, string, string>;
+/**
+ * Hydrates a complete `WorkflowDocument` into a live `Step` tree.
+ *
+ * @public
+ * @param doc - Validated workflow document (version 1).
+ * @param ctx - Hydration context with tool registry and step executor.
+ * @returns The root `Step` of the hydrated workflow.
+ */
+export declare function hydrateWorkflow(doc: WorkflowDocument, ctx: HydrationContext): Step<ContextMemory, string, string>;

package/dist/builders/workflow-hydrator.js

@@ -0,0 +1,336 @@
+/**
+ * Converts a validated `WorkflowDocument` into a live `Step` tree.
+ *
+ * Each node kind maps to the corresponding builder (`step.llm`, `fork`,
+ * `loop`, etc.) so hydrated steps are indistinguishable from programmatic
+ * ones — they register in the step registry, carry retry policies, etc.
+ */
+import { NoeticConfigError } from '../errors/noetic-config-error.js';
+import { all, any } from '../until/combinators.js';
+import { until } from '../until/predicates.js';
+import { frameworkCast } from '../util/framework-cast.js';
+import { branch, fork } from './control-flow-builders.js';
+import { every } from './every.js';
+import { loop } from './loop-builder.js';
+import { provide } from './provide-builder.js';
+import { spawn } from './spawn-builder.js';
+import { step } from './step-builders.js';
+//#endregion
+//#region Until Predicate Hydration
+function hydrateUntilPredicate(pred) {
+    switch (pred.kind) {
+        case 'maxSteps':
+            return until.maxSteps(pred.n);
+        case 'maxCost':
+            return until.maxCost(pred.usd);
+        case 'maxDuration':
+            return until.maxDuration(pred.ms);
+        case 'noToolCalls':
+            return until.noToolCalls();
+        case 'outputContains':
+            return until.outputContains(pred.marker);
+        case 'outputEquals':
+            return until.outputEquals(pred.sentinel);
+        case 'converged':
+            return until.converged({
+                threshold: pred.threshold,
+            });
+        case 'any':
+            return any(...pred.predicates.map(hydrateUntilPredicate));
+        case 'all':
+            return all(...pred.predicates.map(hydrateUntilPredicate));
+        default:
+            throw new NoeticConfigError({
+                code: 'UNKNOWN_UNTIL_PREDICATE',
+                message: `Unknown until predicate kind: '${frameworkCast(pred).kind}'.`,
+                hint: 'Supported kinds: maxSteps, maxCost, maxDuration, noToolCalls, outputContains, outputEquals, converged, any, all.',
+            });
+    }
+}
+//#endregion
+//#region Node Hydrators
+function hydrateLlmNode(node, ctx) {
+    if (node.kind !== 'llm') {
+        return frameworkCast(undefined);
+    }
+    const resolvedTools = resolveTools(node.tools, ctx.tools);
+    return step.llm({
+        id: node.id,
+        model: node.model ?? 'openai/gpt-4o',
+        instructions: node.instructions,
+        tools: resolvedTools.length > 0 ? resolvedTools : undefined,
+        params: node.params,
+    });
+}
+function hydrateToolNode(node, ctx) {
+    if (node.kind !== 'tool') {
+        return frameworkCast(undefined);
+    }
+    const resolved = ctx.tools.get(node.toolName);
+    if (!resolved) {
+        throw new NoeticConfigError({
+            code: 'UNKNOWN_TOOL_REFERENCE',
+            message: `Tool '${node.toolName}' referenced in workflow node '${node.id}' is not registered.`,
+            hint: `Available tools: ${[
+                ...ctx.tools.keys(),
+            ].join(', ') || '(none)'}`,
+        });
+    }
+    return frameworkCast(step.run({
+        id: node.id,
+        execute: async (_input, execCtx) => {
+            const args = node.args ?? {};
+            const callId = `call-${node.id}-${Date.now()}`;
+            const callItem = {
+                id: callId,
+                type: 'function_call',
+                status: 'completed',
+                name: node.toolName,
+                callId,
+                arguments: JSON.stringify(args),
+            };
+            execCtx.itemLog.append(callItem);
+            const toolCtx = {
+                ctx: execCtx,
+                harness: execCtx.harness,
+                fs: execCtx.fs,
+                shell: execCtx.shell,
+                memory: {
+                    get: (_layerId) => undefined,
+                    set: (_layerId, _state) => { },
+                },
+                assembledView: execCtx.itemLog.items,
+                lastStepMeta: execCtx.lastStepMeta,
+            };
+            const result = await resolved.execute(args, toolCtx);
+            return stringifyResult(result);
+        },
+    }));
+}
+function hydrateBranchNode(node, ctx) {
+    if (node.kind !== 'branch') {
+        return frameworkCast(undefined);
+    }
+    const hydratedRoutes = node.routes.map((r) => ({
+        match: r.match,
+        target: hydrateNode(r.target, ctx),
+    }));
+    const defaultTarget = node.default ? hydrateNode(node.default, ctx) : null;
+    const allTargets = hydratedRoutes.map((r) => r.target);
+    if (defaultTarget) {
+        allTargets.push(defaultTarget);
+    }
+    return branch({
+        id: node.id,
+        route: (input) => {
+            const trimmed = input.trim().toLowerCase();
+            for (const r of hydratedRoutes) {
+                if (trimmed.includes(r.match.toLowerCase())) {
+                    return r.target;
+                }
+            }
+            return defaultTarget;
+        },
+        _optimizable: frameworkCast(allTargets),
+    });
+}
+function hydrateForkNode(node, ctx) {
+    if (node.kind !== 'fork') {
+        return frameworkCast(undefined);
+    }
+    const hydratedPaths = node.paths.map((p) => hydrateNode(p, ctx));
+    if (node.mode === 'race') {
+        return fork({
+            id: node.id,
+            mode: 'race',
+            paths: () => hydratedPaths,
+            concurrency: node.concurrency,
+            _optimizable: frameworkCast(hydratedPaths),
+        });
+    }
+    const mergeFn = buildMerge(node.merge ?? 'last');
+    if (node.mode === 'settle') {
+        return fork({
+            id: node.id,
+            mode: 'settle',
+            paths: () => hydratedPaths,
+            merge: (results) => {
+                const values = results.filter((r) => r.status === 'fulfilled').map((r) => r.value ?? '');
+                return mergeFn(values);
+            },
+            concurrency: node.concurrency,
+            _optimizable: frameworkCast(hydratedPaths),
+        });
+    }
+    return fork({
+        id: node.id,
+        mode: 'all',
+        paths: () => hydratedPaths,
+        merge: mergeFn,
+        concurrency: node.concurrency,
+        _optimizable: frameworkCast(hydratedPaths),
+    });
+}
+function hydrateSpawnNode(node, ctx) {
+    if (node.kind !== 'spawn') {
+        return frameworkCast(undefined);
+    }
+    return spawn({
+        id: node.id,
+        child: hydrateNode(node.child, ctx),
+        timeout: node.timeout,
+    });
+}
+function hydrateProvideNode(node, ctx) {
+    if (node.kind !== 'provide') {
+        return frameworkCast(undefined);
+    }
+    const resolvedLayers = ctx.layers
+        ? node.layers.map((name) => {
+            const layer = ctx.layers?.get(name);
+            if (!layer) {
+                throw new NoeticConfigError({
+                    code: 'UNKNOWN_LAYER_REFERENCE',
+                    message: `Memory layer '${name}' referenced in provide node '${node.id}' is not registered.`,
+                    hint: `Available layers: ${[
+                        ...(ctx.layers?.keys() ?? []),
+                    ].join(', ') || '(none)'}. Pass named layers via HydrationContext.layers.`,
+                });
+            }
+            return layer;
+        })
+        : [];
+    return provide({
+        id: node.id,
+        child: hydrateNode(node.child, ctx),
+        memory: resolvedLayers,
+    });
+}
+function hydrateLoopNode(node, ctx) {
+    if (node.kind !== 'loop') {
+        return frameworkCast(undefined);
+    }
+    return loop({
+        id: node.id,
+        steps: [
+            hydrateNode(node.body, ctx),
+        ],
+        until: hydrateUntilPredicate(node.until),
+        maxIterations: node.maxIterations,
+    });
+}
+function hydrateSequenceNode(node, ctx) {
+    if (node.kind !== 'sequence') {
+        return frameworkCast(undefined);
+    }
+    const children = node.steps.map((s) => hydrateNode(s, ctx));
+    return frameworkCast(step.run({
+        id: node.id,
+        execute: async (input, execCtx) => {
+            let current = input;
+            for (const child of children) {
+                const childInput = stringifyResult(current);
+                current = await ctx.executeStep(child, childInput, execCtx);
+            }
+            return stringifyResult(current);
+        },
+    }));
+}
+function hydrateEveryNode(node, ctx) {
+    if (node.kind !== 'every') {
+        return frameworkCast(undefined);
+    }
+    return every({
+        id: node.id,
+        step: hydrateNode(node.step, ctx),
+        ms: node.ms,
+        onError: node.onError,
+    });
+}
+//#endregion
+//#region Handler Registry
+const NODE_HYDRATORS = {
+    llm: hydrateLlmNode,
+    tool: hydrateToolNode,
+    branch: hydrateBranchNode,
+    fork: hydrateForkNode,
+    spawn: hydrateSpawnNode,
+    provide: hydrateProvideNode,
+    loop: hydrateLoopNode,
+    sequence: hydrateSequenceNode,
+    every: hydrateEveryNode,
+};
+//#endregion
+//#region Helpers
+function resolveTools(toolNames, registry) {
+    if (!toolNames || toolNames.length === 0) {
+        return [];
+    }
+    return toolNames.map((name) => {
+        const resolved = registry.get(name);
+        if (!resolved) {
+            throw new NoeticConfigError({
+                code: 'UNKNOWN_TOOL_REFERENCE',
+                message: `Tool '${name}' referenced in workflow is not registered.`,
+                hint: `Available tools: ${[
+                    ...registry.keys(),
+                ].join(', ') || '(none)'}`,
+            });
+        }
+        return resolved;
+    });
+}
+function buildMerge(strategy) {
+    if (strategy === 'first') {
+        return (r) => r[0] ?? '';
+    }
+    if (strategy === 'concat') {
+        return (r) => r.join('\n');
+    }
+    return (r) => r[r.length - 1] ?? '';
+}
+function stringifyResult(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (value === null || value === undefined) {
+        return '';
+    }
+    return JSON.stringify(value);
+}
+//#endregion
+//#region Public API
+/**
+ * Hydrates a single `WorkflowNode` into a live `Step`.
+ *
+ * @public
+ * @param node - Validated workflow node.
+ * @param ctx - Hydration context with tool registry and step executor.
+ * @returns A live `Step` ready for execution.
+ * @throws `NoeticConfigError` with code `UNKNOWN_NODE_KIND` if the node kind is unrecognised.
+ * @throws `NoeticConfigError` with code `UNKNOWN_TOOL_REFERENCE` if a tool name cannot be resolved.
+ * @throws `NoeticConfigError` with code `UNKNOWN_UNTIL_PREDICATE` if an until predicate kind is unrecognised.
+ */
+export function hydrateNode(node, ctx) {
+    const hydrator = NODE_HYDRATORS[node.kind];
+    if (!hydrator) {
+        throw new NoeticConfigError({
+            code: 'UNKNOWN_NODE_KIND',
+            message: `Unknown workflow node kind: '${node.kind}'.`,
+            hint: `Supported kinds: ${Object.keys(NODE_HYDRATORS).join(', ')}.`,
+        });
+    }
+    return hydrator(node, ctx);
+}
+/**
+ * Hydrates a complete `WorkflowDocument` into a live `Step` tree.
+ *
+ * @public
+ * @param doc - Validated workflow document (version 1).
+ * @param ctx - Hydration context with tool registry and step executor.
+ * @returns The root `Step` of the hydrated workflow.
+ */
+export function hydrateWorkflow(doc, ctx) {
+    return hydrateNode(doc.root, ctx);
+}
+//#endregion

package/dist/conditions/conditions.d.ts

@@ -1,7 +1,7 @@
-import type { Context } from '../types/context';
-import type { EmbedFn } from '../types/embed';
-import type { ContextMemory, StorageAdapter } from '../types/memory';
-import type { Step } from '../types/step';
+import type { Context } from '../types/context.js';
+import type { EmbedFn } from '../types/embed.js';
+import type { ContextMemory, StorageAdapter } from '../types/memory.js';
+import type { Step } from '../types/step.js';
 export type Condition<I> = (input: I, ctx: Context) => Promise<boolean>;
 export interface WhenClause<TMemory = ContextMemory, I = unknown, O = unknown> {
     readonly kind: 'when';

package/dist/conditions/conditions.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { createMessage, extractAssistantText, trackUsage } from '../interpreter/message-helpers';
-import { cosineSimilarity } from './cosine-similarity';
+import { createMessage, extractAssistantText, trackUsage } from '../util/message-helpers.js';
+import { cosineSimilarity } from './cosine-similarity.js';
 //#endregion
 //#region Helpers
 function serializeInput(input) {

package/dist/errors/noetic-error.d.ts

@@ -1,4 +1,4 @@
-import type { NoeticError } from '../types/error';
+import type { NoeticError } from '../types/error.js';
 /**
  * Runtime error thrown during step execution (LLM failures, fork failures, budget exceeded, etc.).
  *

package/dist/errors/noetic-error.js

@@ -43,6 +43,8 @@ function formatMessage(error) {
             return `Budget exceeded: ${error.field} limit ${error.limit}, actual ${error.actual}`;
         case 'steering_denied':
             return `Steering denied${error.guidance ? `: ${error.guidance}` : ''}`;
+        case 'handle_evicted':
+            return `Subprocess handle '${error.handleId}' evicted (step '${error.stepId}'): adapter returned null for ${error.gracePeriodMs}ms`;
         default: {
             const _exhaustive = error;
             void _exhaustive;