@noetic-tools/core 0.0.1 → 0.1.0

package/dist/adapters/openrouter.js

@@ -1,8 +1,9 @@
 import { z } from 'zod';
-import { frameworkCast } from '../interpreter/framework-cast';
-import { isAssistantMessage } from '../interpreter/typeguards';
+import { NoeticConfigError } from '../errors/noetic-config-error';
 import { buildToolExecutionContext } from '../runtime/tool-memory';
 import { SteeringAction } from '../types/steering';
+import { frameworkCast } from '../util/framework-cast';
+import { isAssistantMessage } from '../util/message-helpers';
 const EmbeddingsResponseSchema = z.object({
     data: z.array(z.object({
         embedding: z.array(z.number()),
@@ -20,6 +21,44 @@ function contentPartsToText(parts) {
         .map((p) => p.text)
         .join('');
 }
+function inputTextPartToProvider(part) {
+    return {
+        type: 'input_text',
+        text: part.text,
+    };
+}
+function inputImagePartToProvider(part) {
+    return {
+        type: 'input_image',
+        imageUrl: part.imageUrl,
+        detail: part.detail ?? 'auto',
+    };
+}
+function inputFilePartToProvider(part) {
+    return {
+        type: 'input_file',
+        filename: part.filename,
+        fileData: part.fileData,
+        fileUrl: part.fileUrl,
+        fileId: part.fileId,
+    };
+}
+function inputContentPartToProvider(part) {
+    if (part.type === 'input_text') {
+        return inputTextPartToProvider(part);
+    }
+    if (part.type === 'input_image') {
+        return inputImagePartToProvider(part);
+    }
+    return inputFilePartToProvider(part);
+}
+function contentPartsToProviderContent(parts) {
+    const hasStructuredInput = parts.some((part) => part.type === 'input_image' || part.type === 'input_file');
+    if (!hasStructuredInput) {
+        return contentPartsToText(parts);
+    }
+    return frameworkCast(parts).map(inputContentPartToProvider);
+}
 //#endregion
 //#region Item → OpenRouter Input Conversion
 /** @internal Extracts system messages from items and returns them as a single instructions string. */
@@ -51,7 +90,7 @@ function itemToInputItem(item) {
         // because the SDK's input union does not accept ResponsesOutputMessage directly.
         return {
             role: item.role,
-            content: contentPartsToText(item.content),
+            content: contentPartsToProviderContent(item.content),
         };
     }
     if (item.type === 'function_call') {
@@ -141,12 +180,22 @@ export function extractUsage(usage) {
 // 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.
+/**
+ * Provider APIs (Anthropic via OpenRouter) enforce tool names match
+ * `^[a-zA-Z0-9_-]{1,64}$`. Noetic's internal layer-tool names use `layerId/fn`
+ * which contains a forbidden `/`. We translate to a wire-safe form only at
+ * the SDK boundary; internal tool-name identity (and every codebase reference
+ * to names like `plan/updatePrd`) is preserved.
+ */
+export function sanitizeToolNameForWire(name) {
+    return name.replace(/[^a-zA-Z0-9_-]/g, '_');
+}
 /** @internal */
 export function convertTools({ tools }) {
     return tools.map((t) => frameworkCast({
         type: 'function',
         function: {
-            name: t.name,
+            name: sanitizeToolNameForWire(t.name),
             description: t.description,
             inputSchema: t.input,
         },
@@ -171,7 +220,12 @@ async function consumeGenerator(generator) {
 }
 /** @internal Execute a single tool call with steering checks. */
 export async function executeToolCall(params) {
-    const matchedTool = params.tools.find((t) => t.name === params.toolName);
+    // Model sees sanitised tool names (see `sanitizeToolNameForWire`). Match
+    // against both the original and sanitised name so internal identity (e.g.
+    // `plan/updatePrd` used by steering whitelists, skill docs, and the
+    // `planMemory.beforeToolCall` hook) stays intact while the wire name is
+    // provider-compliant.
+    const matchedTool = params.tools.find((t) => t.name === params.toolName || sanitizeToolNameForWire(t.name) === params.toolName);
     if (!matchedTool) {
         return {
             output: `Error: unknown tool '${params.toolName}'`,
@@ -223,6 +277,13 @@ export async function executeToolCall(params) {
  * @returns An `EmbedFn` that produces embedding vectors for the given texts.
  */
 export function createOpenRouterEmbed(apiKey, embeddingModel) {
+    if (!apiKey) {
+        throw new NoeticConfigError({
+            code: 'MISSING_API_KEY',
+            message: 'createOpenRouterEmbed() requires an OpenRouter API key.',
+            hint: 'Pass the key explicitly, e.g. createOpenRouterEmbed(process.env.OPENROUTER_API_KEY).',
+        });
+    }
     const model = embeddingModel ?? 'openai/text-embedding-3-small';
     return async (texts) => {
         const response = await fetch('https://openrouter.ai/api/v1/embeddings', {

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

@@ -1,5 +1,6 @@
 import { NoeticConfigError } from '../errors/noetic-config-error';
-import { frameworkCast } from '../interpreter/framework-cast';
+import { getDefaultRegistrar } from '../types/step-registrar';
+import { frameworkCast } from '../util/framework-cast';
 export function fork(opts) {
     if (!opts.id || opts.id.trim() === '') {
         throw new NoeticConfigError({
@@ -15,10 +16,12 @@ export function fork(opts) {
             hint: 'Provide a merge function that combines path results into a single output.',
         });
     }
-    return frameworkCast({
+    const built = frameworkCast({
         kind: 'fork',
         ...opts,
     });
+    getDefaultRegistrar().register(built);
+    return built;
 }
 /**
  * Creates a conditional routing step that selects the next step at runtime.
@@ -46,8 +49,10 @@ export function branch(opts) {
             hint: 'Provide a route function that selects the next step at runtime.',
         });
     }
-    return {
+    const built = {
         kind: 'branch',
         ...opts,
     };
+    getDefaultRegistrar().register(built);
+    return built;
 }

package/dist/builders/every.js

@@ -1,4 +1,5 @@
 import { NoeticConfigError } from '../errors/noetic-config-error';
+import { getDefaultRegistrar } from '../types/step-registrar';
 /**
  * Creates an `every` step that runs a body step on a fixed-interval schedule.
  *
@@ -48,7 +49,7 @@ export function every(opts) {
             hint: 'Pass a non-negative number of milliseconds for jitter, or omit it.',
         });
     }
-    return {
+    const built = {
         kind: 'every',
         id: opts.id,
         step: opts.step,
@@ -57,4 +58,6 @@ export function every(opts) {
         onError: opts.onError ?? 'continue',
         jitter: opts.jitter ?? 0,
     };
+    getDefaultRegistrar().register(built);
+    return built;
 }

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

@@ -1,32 +1 @@
-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>;
+export { layerData, layerFn } from '../memory/layer-provides';

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

@@ -1,33 +1 @@
-/**
- * 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,
-    };
-}
+export { layerData, layerFn } from '../memory/layer-provides';

package/dist/builders/loop-builder.js

@@ -1,4 +1,5 @@
 import { NoeticConfigError } from '../errors/noetic-config-error';
+import { getDefaultRegistrar } from '../types/step-registrar';
 /**
  * Creates a loop step that iterates a body step until a termination predicate is satisfied.
  *
@@ -39,8 +40,10 @@ export function loop(opts) {
             hint: 'Provide an until predicate, e.g. until.maxSteps(10).',
         });
     }
-    return {
+    const built = {
         kind: 'loop',
         ...opts,
     };
+    getDefaultRegistrar().register(built);
+    return built;
 }

package/dist/builders/memory-builder.js

@@ -1,4 +1,4 @@
-import { frameworkCast } from '../interpreter/framework-cast';
+import { frameworkCast } from '../util/framework-cast';
 /**
  * Creates a type-safe memory configuration from a tuple of memory layers.
  * The returned config preserves literal layer types for compile-time inference

package/dist/builders/provide-builder.js

@@ -1,4 +1,5 @@
 import { NoeticConfigError } from '../errors/noetic-config-error';
+import { getDefaultRegistrar } from '../types/step-registrar';
 /**
  * Creates a provide step that attaches memory layers to its child without creating an isolated context.
  * Like React's Context.Provider — layers are available to all descendant steps.
@@ -27,8 +28,10 @@ export function provide(opts) {
             hint: 'Provide a child step to execute with the provided memory layers.',
         });
     }
-    return {
+    const built = {
         kind: 'provide',
         ...opts,
     };
+    getDefaultRegistrar().register(built);
+    return built;
 }

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

@@ -1,5 +1,18 @@
 import type { ContextMemory, MemoryConfig, MemoryLayer } from '../types/memory';
 import type { Step, StepSpawn } from '../types/step';
+import type { SubprocessAdapter } from '../types/subprocess-adapter';
+interface SpawnOpts<TMemory, I, O> {
+    id: string;
+    child: Step<TMemory, I, O>;
+    memory?: MemoryConfig | MemoryLayer[];
+    timeout?: number;
+    /**
+     * Optional per-step subprocess adapter override. The interpreter routes
+     * this spawn through the given adapter instead of the harness default.
+     * See spec 04 for the `overrides ?? step ?? harness` precedence rule.
+     */
+    subprocess?: SubprocessAdapter;
+}
 /**
  * Creates a spawn step that executes a child step in an isolated context boundary.
  *
@@ -8,13 +21,13 @@ import type { Step, StepSpawn } from '../types/step';
  * @param opts.child - Step to execute in the isolated child context.
  * @param opts.memory - Optional memory config or layers for the child context (replaces parent layers entirely).
  * @param opts.timeout - Optional execution timeout in ms; the child is aborted if it exceeds this.
- * @returns A `StepSpawn` step.
+ * @param opts.subprocess - Optional per-step subprocess adapter override.
+ * @returns A `StepSpawn` step. The spawn step and its `child` step are both
+ *   auto-registered in the shared step registry so the subprocess adapter
+ *   can dispatch either by id.
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  * @throws `NoeticConfigError` with code `MISSING_CHILD_STEP` if `child` is not provided.
+ * @throws `NoeticConfigError` with code `DUPLICATE_STEP_ID` if another step with the same id is already registered.
  */
-export declare function spawn<TMemory = ContextMemory, I = unknown, O = unknown>(opts: {
-    id: string;
-    child: Step<TMemory, I, O>;
-    memory?: MemoryConfig | MemoryLayer[];
-    timeout?: number;
-}): StepSpawn<TMemory, I, O>;
+export declare function spawn<TMemory = ContextMemory, I = unknown, O = unknown>(opts: SpawnOpts<TMemory, I, O>): StepSpawn<TMemory, I, O>;
+export {};

package/dist/builders/spawn-builder.js

@@ -1,4 +1,7 @@
 import { NoeticConfigError } from '../errors/noetic-config-error';
+import { getDefaultRegistrar } from '../types/step-registrar';
+//#endregion
+//#region Public API
 /**
  * Creates a spawn step that executes a child step in an isolated context boundary.
  *
@@ -7,9 +10,13 @@ import { NoeticConfigError } from '../errors/noetic-config-error';
  * @param opts.child - Step to execute in the isolated child context.
  * @param opts.memory - Optional memory config or layers for the child context (replaces parent layers entirely).
  * @param opts.timeout - Optional execution timeout in ms; the child is aborted if it exceeds this.
- * @returns A `StepSpawn` step.
+ * @param opts.subprocess - Optional per-step subprocess adapter override.
+ * @returns A `StepSpawn` step. The spawn step and its `child` step are both
+ *   auto-registered in the shared step registry so the subprocess adapter
+ *   can dispatch either by id.
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  * @throws `NoeticConfigError` with code `MISSING_CHILD_STEP` if `child` is not provided.
+ * @throws `NoeticConfigError` with code `DUPLICATE_STEP_ID` if another step with the same id is already registered.
  */
 export function spawn(opts) {
     if (!opts.id?.trim()) {
@@ -26,8 +33,15 @@ export function spawn(opts) {
             hint: 'Provide a child step to execute in the isolated child context.',
         });
     }
-    return {
+    const built = {
         kind: 'spawn',
         ...opts,
     };
+    getDefaultRegistrar().register(built);
+    // Ensure the child is addressable by id — builders for `run`/`llm`/`tool`
+    // self-register, but a caller can construct a step literal and pass it as
+    // `child` without going through a builder.
+    getDefaultRegistrar().register(opts.child);
+    return built;
 }
+//#endregion

package/dist/builders/step-builders.d.ts

@@ -1,8 +1,38 @@
 import type { ZodType } from 'zod';
-import type { ModelParams, RetryPolicy, Tool } from '../types/common';
+import type { ModelParams, RetryPolicy } from '../types/common';
 import type { Context } from '../types/context';
 import type { ContextMemory } from '../types/memory';
-import type { StepLLM, StepRun, StepTool } from '../types/step';
+import type { Lazy, StepLLM, StepRun, StepTool } from '../types/step';
+import type { SubprocessAdapter } from '../types/subprocess-adapter';
+import type { Tool } from '../types/tool';
+interface StepRunOpts<TMemory, I, O> {
+    id: string;
+    execute: (input: I, ctx: Context<TMemory>) => Promise<O>;
+    retry?: RetryPolicy;
+    /**
+     * Optional subprocess adapter override. When set, `execute()` is routed
+     * through this adapter instead of the harness default. See spec 04 for
+     * precedence rules.
+     */
+    subprocess?: SubprocessAdapter;
+}
+interface StepLLMOpts<TMemory, O> {
+    id: string;
+    /** Model id. Eager string or `(ctx) => string` getter (resolved at step execution). */
+    model: Lazy<string, TMemory>;
+    /** Optional instructions; eager string or `(ctx) => string | undefined` getter. */
+    instructions?: Lazy<string | undefined, TMemory>;
+    /** Optional tools; eager array or `(ctx) => Tool[] | undefined` getter. */
+    tools?: Lazy<Tool[] | undefined, TMemory>;
+    output?: ZodType<O>;
+    params?: ModelParams;
+    emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
+}
+interface StepToolOpts<I, O> {
+    id: string;
+    tool: Tool<ZodType<I>, ZodType<O>>;
+    args?: Partial<I>;
+}
 export declare const step: {
     /**
      * Creates a pure async computation step.
@@ -11,38 +41,31 @@ export declare 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<TMemory = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: {
-        id: string;
-        execute: (input: I, ctx: Context<TMemory>) => Promise<O>;
-        retry?: RetryPolicy;
-    }): StepRun<TMemory, I, O>;
+    run<TMemory = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: StepRunOpts<TMemory, I, O>): StepRun<TMemory, I, O>;
     /**
      * 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<TMemory = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: {
-        id: string;
-        model: string;
-        instructions?: string;
-        tools?: Tool[];
-        output?: ZodType<O>;
-        params?: ModelParams;
-        emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
-    }): StepLLM<TMemory, I, O>;
+    llm<TMemory = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: StepLLMOpts<TMemory, O>): StepLLM<TMemory, I, O>;
     /**
      * Creates a tool execution step that invokes a typed tool definition.
      *
@@ -50,13 +73,11 @@ export declare 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.
      */
-    tool<TMemory = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: {
-        id: string;
-        tool: Tool<ZodType<I>, ZodType<O>>;
-        args?: Partial<I>;
-    }): StepTool<TMemory, I, O>;
+    tool<TMemory = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: StepToolOpts<I, O>): StepTool<TMemory, I, O>;
 };
+export {};

package/dist/builders/step-builders.js

@@ -1,4 +1,7 @@
 import { NoeticConfigError } from '../errors/noetic-config-error';
+import { getDefaultRegistrar } from '../types/step-registrar';
+//#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,6 +1,6 @@
 import type { ZodTypeAny, z } from 'zod';
-import type { Tool } from '../types/common';
 import type { FunctionCallItem, FunctionCallOutputItem, Item, ItemSchemaExtensions, ToolResultExtensionItem } from '../types/items';
+import type { Tool, ToolMemoryDeclaration } from '../types/tool';
 import type { ToolExecutionContext } from '../types/tool-context';
 interface ToolConfig<I extends ZodTypeAny, O extends ZodTypeAny> {
     name: 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

@@ -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